Skip to main content

User Token

Manage user tokens for authentication and access control including AAA (Authentication, Authorization, Accounting) profile information.

Base URL: https://gate.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Endpoints

GET /user_token/

Retrieve a list of user tokens with AAA profile information and optional filtering.

Parameters:

Parameter Type In Required Description
username string query No Filter users by username field
organization string query No Filter users by organization field
limit integer query No Number of results to return per page
offset integer query No The initial index from which to return the results
balance boolean query No Include remaining balance (in seconds)

Example Request:

GET /api/v1/user_token/?username=john_doe&balance=true&limit=10

Example Response:

{
  "count": 25,
  "next": "https://gate.zequenze.com/api/v1/user_token/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": 1,
      "username": "john_doe",
      "organization": "acme_corp",
      "created_at": "2024-01-15T10:30:00Z",
      "last_login": "2024-01-20T14:22:00Z",
      "balance_seconds": 3600,
      "profile": {
        "email": "john@example.com",
        "role": "admin"
      }
    }
  ]
}
Status Description
200 Success
401 Unauthorized

POST /user_token/

Create a new user token with AAA profile information.

Parameters:

Parameter Type In Required Description
data object body Yes User token creation data

Example Request:

POST /api/v1/user_token/
Content-Type: application/json

{
  "username": "jane_smith",
  "organization": "tech_solutions",
  "email": "jane@techsolutions.com",
  "role": "user",
  "balance_seconds": 7200
}

Example Response:

{
  "id": 15,
  "username": "jane_smith",
  "organization": "tech_solutions",
  "created_at": "2024-01-21T09:15:00Z",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "profile": {
    "email": "jane@techsolutions.com",
    "role": "user"
  }
}
Status Description
201 Created successfully
400 Bad request - invalid data
401 Unauthorized

GET /user_token/{id}/

Retrieve a specific user token by ID including AAA profile information.

Parameters:

Parameter Type In Required Description
id integer path Yes User token ID
balance boolean query No Include remaining balance (in seconds)

Example Request:

GET /api/v1/user_token/15/?balance=true

Example Response:

{
  "id": 15,
  "username": "jane_smith",
  "organization": "tech_solutions",
  "created_at": "2024-01-21T09:15:00Z",
  "last_login": "2024-01-21T11:30:00Z",
  "balance_seconds": 6840,
  "profile": {
    "email": "jane@techsolutions.com",
    "role": "user",
    "permissions": ["read", "write"]
  }
}
Status Description
200 Success
401 Unauthorized
404 User token not found

PUT /user_token/{id}/

Update a user token completely, replacing all fields.

Parameters:

Parameter Type In Required Description
id integer path Yes User token ID
data object body Yes Complete user token data

Example Request:

PUT /api/v1/user_token/15/
Content-Type: application/json

{
  "username": "jane_smith_updated",
  "organization": "tech_solutions",
  "email": "jane.smith@techsolutions.com",
  "role": "admin",
  "balance_seconds": 10800
}

Example Response:

{
  "id": 15,
  "username": "jane_smith_updated",
  "organization": "tech_solutions",
  "updated_at": "2024-01-21T12:00:00Z",
  "profile": {
    "email": "jane.smith@techsolutions.com",
    "role": "admin"
  }
}
Status Description
200 Updated successfully
400 Bad request - invalid data
401 Unauthorized
404 User token not found

PATCH /user_token/{id}/

Partially update a user token, modifying only specified fields.

Parameters:

Parameter Type In Required Description
id integer path Yes User token ID
data object body Yes Partial user token data

Example Request:

PATCH /api/v1/user_token/15/
Content-Type: application/json

{
  "role": "moderator",
  "balance_seconds": 14400
}

Example Response:

{
  "id": 15,
  "username": "jane_smith_updated",
  "organization": "tech_solutions",
  "updated_at": "2024-01-21T12:30:00Z",
  "profile": {
    "email": "jane.smith@techsolutions.com",
    "role": "moderator"
  }
}
Status Description
200 Updated successfully
400 Bad request - invalid data
401 Unauthorized
404 User token not found

DELETE /user_token/{id}/

Delete a specific user token permanently.

Parameters:

Parameter Type In Required Description
id integer path Yes User token ID

Example Request:

DELETE /api/v1/user_token/15/
Status Description
204 Deleted successfully
401 Unauthorized
404 User token not found

Best Practices

  • Token Security: Store API tokens securely and rotate them regularly
  • Balance Monitoring: Use the balance parameter to track remaining time allocations
  • Filtering: Combine username and organization filters for efficient user searches
  • Pagination: Always use limit and offset parameters for large datasets to improve performance
  • Error Handling: Implement proper error handling for 401 (expired tokens) and 404 (missing resources) responses
  • Partial Updates: Use PATCH instead of PUT when updating only specific fields to reduce bandwidth and processing overhead
Back to top