Skip to main content

User Token

The User Token API provides comprehensive user management capabilities including AAA (Authentication, Authorization, and Accounting) profile information. These endpoints allow you to create, retrieve, update, and delete user accounts along with their associated token-based authentication credentials and usage tracking.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The User Token API is designed for managing user accounts in systems that require token-based authentication and usage tracking. This API category is particularly useful for:

  • User Account Management: Create and maintain user profiles with organization-based filtering
  • AAA Integration: Handle Authentication, Authorization, and Accounting data for network access control
  • Usage Monitoring: Track user token balances and consumption in time-based systems
  • Multi-tenant Operations: Filter and manage users across different organizations

These endpoints work together to provide a complete user lifecycle management system. The list and read operations support balance tracking, allowing you to monitor remaining token time in seconds. This makes the API ideal for time-based access control systems, VPN services, or any application where user access is metered by duration.

Key concepts include user tokens that represent time-based access credits, organization-based user segmentation for multi-tenant environments, and real-time balance tracking for usage monitoring.

Endpoints

GET /user_token/

Description: Retrieves a paginated list of all users with their AAA profile information. This endpoint supports filtering by username and organization, making it ideal for administrative dashboards and user search functionality.

Use Cases:

  • Display all users in an administrative interface
  • Search for specific users by username
  • Filter users by organization in multi-tenant systems
  • Monitor user token balances across your system

Full URL Example:

https://gate.zequenze.com/api/v1/user_token/?username=john_doe&organization=acme_corp&balance=true&limit=20&offset=0

Parameters:

Parameter Type In Required Description
username string query No Filter results to show only users matching this exact username
organization string query No Filter results to show only users belonging to this organization
limit integer query No Number of results to return per page (default: 20, max: 100)
offset integer query No Starting position for results (used for pagination)
balance boolean query No When true, includes remaining balance in seconds for each user

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/user_token/?organization=acme_corp&balance=true&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 45,
  "next": "https://gate.zequenze.com/api/v1/user_token/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": 1,
      "username": "john_doe",
      "email": "john@acmecorp.com",
      "organization": "acme_corp",
      "is_active": true,
      "token": "tok_abc123def456",
      "balance_seconds": 86400,
      "created_at": "2024-01-15T10:30:00Z",
      "last_login": "2024-01-20T14:22:00Z",
      "profile": {
        "max_sessions": 2,
        "access_level": "premium"
      }
    },
    {
      "id": 2,
      "username": "jane_smith",
      "email": "jane@acmecorp.com",
      "organization": "acme_corp",
      "is_active": true,
      "token": "tok_xyz789abc012",
      "balance_seconds": 43200,
      "created_at": "2024-01-16T09:15:00Z",
      "last_login": "2024-01-21T11:45:00Z",
      "profile": {
        "max_sessions": 1,
        "access_level": "standard"
      }
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of users
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to list users

POST /user_token/

Description: Creates a new user account with AAA profile information and generates an associated authentication token. This endpoint is essential for user onboarding and account provisioning workflows.

Use Cases:

  • Register new users in your system
  • Bulk user creation for organization onboarding
  • Provision accounts with specific access levels and time allowances
  • Create temporary access accounts with predefined expiration

Full URL Example:

https://gate.zequenze.com/api/v1/user_token/

Parameters:

Parameter Type In Required Description
data object body Yes JSON object containing user information and profile settings

cURL Example:

curl -X POST "https://gate.zequenze.com/api/v1/user_token/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new_user",
    "email": "newuser@company.com",
    "organization": "tech_startup",
    "is_active": true,
    "initial_balance_seconds": 172800,
    "profile": {
      "max_sessions": 3,
      "access_level": "premium"
    }
  }'

Example Response:

{
  "id": 15,
  "username": "new_user",
  "email": "newuser@company.com",
  "organization": "tech_startup",
  "is_active": true,
  "token": "tok_new456user789",
  "balance_seconds": 172800,
  "created_at": "2024-01-21T16:30:00Z",
  "last_login": null,
  "profile": {
    "max_sessions": 3,
    "access_level": "premium"
  }
}

Response Codes:

Status Description
201 Created - User successfully created with token
400 Bad Request - Invalid data provided
401 Unauthorized - Invalid or missing API token
409 Conflict - Username already exists

GET /user_token/{id}/

Description: Retrieves detailed information for a specific user by their ID, including AAA profile data and optionally their current token balance. This endpoint is perfect for user profile pages and account status checks.

Use Cases:

  • Display user profile information
  • Check current token balance for a specific user
  • Retrieve user details for administrative review
  • Validate user account status before granting access

Full URL Example:

https://gate.zequenze.com/api/v1/user_token/15/?balance=true

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the user to retrieve
balance boolean query No Include current remaining balance in seconds

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/user_token/15/?balance=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 15,
  "username": "new_user",
  "email": "newuser@company.com",
  "organization": "tech_startup",
  "is_active": true,
  "token": "tok_new456user789",
  "balance_seconds": 158400,
  "created_at": "2024-01-21T16:30:00Z",
  "last_login": "2024-01-22T08:15:00Z",
  "profile": {
    "max_sessions": 3,
    "access_level": "premium",
    "total_usage_seconds": 14400,
    "last_activity": "2024-01-22T12:30:00Z"
  }
}

Response Codes:

Status Description
200 Success - Returns user details
401 Unauthorized - Invalid or missing API token
404 Not Found - User with specified ID does not exist

PUT /user_token/{id}/

Description: Completely updates a user's information and AAA profile data. This endpoint replaces all updatable fields with the provided data, making it ideal for comprehensive user profile updates.

Use Cases:

  • Update user profile information completely
  • Change organization assignment
  • Modify access levels and session limits
  • Reset user tokens and balances

Full URL Example:

https://gate.zequenze.com/api/v1/user_token/15/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the user to update
data object body Yes Complete user data object with all fields to update

cURL Example:

curl -X PUT "https://gate.zequenze.com/api/v1/user_token/15/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "updated_user",
    "email": "updated@company.com",
    "organization": "enterprise_corp",
    "is_active": true,
    "balance_seconds": 259200,
    "profile": {
      "max_sessions": 5,
      "access_level": "enterprise"
    }
  }'

Example Response:

{
  "id": 15,
  "username": "updated_user",
  "email": "updated@company.com",
  "organization": "enterprise_corp",
  "is_active": true,
  "token": "tok_new456user789",
  "balance_seconds": 259200,
  "created_at": "2024-01-21T16:30:00Z",
  "updated_at": "2024-01-23T10:45:00Z",
  "last_login": "2024-01-22T08:15:00Z",
  "profile": {
    "max_sessions": 5,
    "access_level": "enterprise"
  }
}

Response Codes:

Status Description
200 Success - User successfully updated
400 Bad Request - Invalid data provided
401 Unauthorized - Invalid or missing API token
404 Not Found - User with specified ID does not exist

PATCH /user_token/{id}/

Description: Partially updates specific fields of a user's profile without affecting other data. This endpoint is perfect for making targeted changes like updating email addresses, adjusting balances, or modifying specific profile settings.

Use Cases:

  • Update only specific user fields (email, balance, etc.)
  • Add time to user token balance
  • Toggle user active status
  • Modify individual profile settings

Full URL Example:

https://gate.zequenze.com/api/v1/user_token/15/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the user to update
data object body Yes Partial user data object containing only fields to update

cURL Example:

curl -X PATCH "https://gate.zequenze.com/api/v1/user_token/15/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "balance_seconds": 345600,
    "profile": {
      "max_sessions": 4
    }
  }'

Example Response:

{
  "id": 15,
  "username": "updated_user",
  "email": "updated@company.com",
  "organization": "enterprise_corp",
  "is_active": true,
  "token": "tok_new456user789",
  "balance_seconds": 345600,
  "created_at": "2024-01-21T16:30:00Z",
  "updated_at": "2024-01-23T14:20:00Z",
  "last_login": "2024-01-22T08:15:00Z",
  "profile": {
    "max_sessions": 4,
    "access_level": "enterprise"
  }
}

Response Codes:

Status Description
200 Success - User partially updated
400 Bad Request - Invalid data provided
401 Unauthorized - Invalid or missing API token
404 Not Found - User with specified ID does not exist

DELETE /user_token/{id}/

Description: Permanently removes a user account and associated token from the system. This action is irreversible and will immediately revoke all access for the specified user.

Use Cases:

  • Remove inactive or expired user accounts
  • Clean up test accounts
  • Comply with data deletion requests
  • Revoke access for terminated users

Full URL Example:

https://gate.zequenze.com/api/v1/user_token/15/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the user to delete

cURL Example:

curl -X DELETE "https://gate.zequenze.com/api/v1/user_token/15/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Codes:

Status Description
204 No Content - User successfully deleted
401 Unauthorized - Invalid or missing API token
404 Not Found - User with specified ID does not exist
409 Conflict - User cannot be deleted due to active sessions

Common Use Cases

User Onboarding and Management

Create new user accounts with appropriate token balances and organization assignments. Use the POST endpoint to provision accounts, then GET to verify creation and monitor initial usage patterns.

Balance Monitoring and Top-ups

Regularly check user token balances using the GET endpoints with the balance parameter. Use PATCH to add time to user accounts when they purchase additional credits or need balance adjustments.

Organization-based User Administration

Filter users by organization using the list endpoint to manage multi-tenant environments. This is particularly useful for service providers managing multiple client organizations.

Account Lifecycle Management

Track user activity from creation to deletion. Use the read endpoint to monitor usage patterns, update profiles as needed, and ultimately delete inactive accounts to maintain system hygiene.

Bulk Operations and Reporting

Combine the list endpoint with pagination to process all users in batches for reporting, billing, or maintenance operations. The organization and balance filters help create targeted reports.

Best Practices

  • Pagination: Always use limit and offset parameters when retrieving user lists to avoid performance issues with large datasets. Start with reasonable page sizes (20-50 users) and adjust based on your needs.

  • Balance Monitoring: Include the balance parameter in GET requests only when you need current usage data, as this may add processing overhead for real-time calculations.

  • Error Handling: Always check for 404 errors when working with specific user IDs, and implement proper retry logic for network timeouts. Handle 409 conflicts gracefully during user creation.

  • Security: Never log or expose user tokens in client-side code. Implement proper token rotation policies and monitor for unusual usage patterns that might indicate token compromise.

  • Performance: Use PATCH instead of PUT for small updates to minimize data transfer and processing time. Cache user profile data when possible to reduce API calls.

  • Data Consistency: When updating user organizations or access levels, ensure your application logic accounts for any active sessions that might be affected by the changes.

Back to top