User Token

ManageThe User Token API provides comprehensive user tokensmanagement for authentication and access controlcapabilities 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/

RetrieveDescription: Retrieves a paginated list of userall tokensusers with their AAA profile informationinformation. This endpoint supports filtering by username and optionalorganization, filtering.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 bymatching this exact username field
organization	string	query	No	Filter results to show only users bybelonging to this organization field
limit	integer	query	No	Number of results to return per page (default: 20, max: 100)
offset	integer	query	No	TheStarting initialposition index from which to return thefor results (used for pagination)
balance	boolean	query	No	IncludeWhen true, includes remaining balance (in seconds)seconds for each user

ExamplecURL Request:Example:

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

Example Response:

{
  "count": 25,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": 3600,43200,
      "created_at": "2024-01-16T09:15:00Z",
      "last_login": "2024-01-21T11:45:00Z",
      "profile": {
        "email"max_sessions": 1,
        "access_level": "john@example.com",
        "role": "admin"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/

CreateDescription: Creates a new user tokenaccount with AAA profile information.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	UserJSON tokenobject creationcontaining datauser information and profile settings

ExamplecURL Request:Example:

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

Example Response:

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

Response Codes:

Status	Description
201	Created - User successfully created with token
400	Bad requestRequest - invalidInvalid data provided
401	Unauthorized - Invalid or missing API token

409 Conflict - Username already exists

---

GET /user_token/{id}/

RetrieveDescription: Retrieves detailed information for a specific user token by IDtheir ID, including AAA profile information.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	UserUnique tokenidentifier IDof the user to retrieve
balance	boolean	query	No	Include current remaining balance (in seconds)seconds

ExamplecURL Request:Example:

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

Example Response:

{
  "id": 15,
  "username": "jane_smith"new_user",
  "email": "newuser@company.com",
  "organization": "tech_solutions"tech_startup",
  "is_active": true,
  "token": "tok_new456user789",
  "balance_seconds": 158400,
  "created_at": "2024-01-21T09:15:21T16:30:00Z",
  "last_login": "2024-01-21T11:30:22T08:15:00Z",
  "balance_seconds": 6840,
  "profile": {
    "email"max_sessions": 3,
    "access_level": "jane@techsolutions.com"premium",
    "role"total_usage_seconds": 14400,
    "last_activity": "user",
    "permissions": ["read", "write"]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 tokenwith specified ID does not foundexist

---

PUT /user_token/{id}/

UpdateDescription: Completely updates a useruser's tokeninformation completely,and replacingAAA profile data. This endpoint replaces all fields.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	UserUnique tokenidentifier IDof the user to update
data	object	body	Yes	Complete user tokendata dataobject with all fields to update

ExamplecURL Request:Example:

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

Example Response:

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

Response Codes:

Status	Description
200	UpdatedSuccess - User successfully updated
400	Bad requestRequest - invalidInvalid data provided
401	Unauthorized - Invalid or missing API token
404	Not Found - User tokenwith specified ID does not foundexist

---

PATCH /user_token/{id}/

Description: Partially updateupdates specific fields of a useruser's token,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 specifiedspecific fields.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	UserUnique tokenidentifier IDof the user to update
data	object	body	Yes	Partial user tokendata dataobject containing only fields to update

ExamplecURL Request:Example:

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

Example Response:

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

Response Codes:

Status	Description
200	UpdatedSuccess successfully- User partially updated
400	Bad requestRequest - invalidInvalid data provided
401	Unauthorized - Invalid or missing API token
404	Not Found - User tokenwith specified ID does not foundexist

---

DELETE /user_token/{id}/

DeleteDescription: Permanently removes a specificuser 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 tokenaccounts permanently.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	UserUnique tokenidentifier IDof the user to delete

ExamplecURL Request:Example:

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

Response Codes:

Status	Description
204	DeletedNo Content - User successfully deleted
401	Unauthorized - Invalid or missing API token
404	Not Found - User tokenwith specified ID does not foundexist

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

• Token Security:Pagination 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 forwhen retrieving user lists to avoid performance issues with large datasetsdatasets. toStart improvewith performancereasonable 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: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 errortoken handlingrotation policies and monitor for 401unusual (expiredusage tokens)patterns andthat 404might (missingindicate resources)token responsescompromise.

Partial Updates:Performance: Use PATCH instead of PUT for small updates to minimize data transfer and processing time. Cache user profile data when updating only specific fieldspossible to reduce bandwidthAPI andcalls.

processing overhead

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.