Skip to main content

User Token

The User Token API provides comprehensive user management functionality with integrated AAA (Authentication, Authorization, and Accounting) profile support. These endpoints allow you to create, retrieve, update, and delete users while managing their authentication credentials, time-based balances, and access profiles for your organization's systems.

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 users in systems that require time-based access control, quota management, and organizational segmentation. This API is particularly useful for:

  • Network Access Control: Managing user credentials and time quotas for network services
  • Service Provider Management: Tracking user balances and service class assignments
  • Multi-tenant Organizations: Organizing users across different organizations with custom profiles
  • External System Integration: Synchronizing user data with external databases using external_id references

Key features include:

  • Time-based Quotas: Track user time balances in seconds for usage-based services
  • AAA Profile Integration: Assign authentication, authorization, and accounting profiles to users
  • Expiration Management: Set automatic user expiration dates
  • Organizational Segmentation: Group users by organization for multi-tenant scenarios
  • External System Sync: Link users to external systems via external_id for seamless integration

The API supports both individual user operations and bulk listing with advanced filtering capabilities, making it suitable for both administrative interfaces and automated user provisioning systems.

Endpoints

GET /user_token/

Description: Retrieves a paginated list of users with their AAA profile information and optional balance data. This endpoint is essential for building user management interfaces, generating reports, and monitoring user accounts across your organization.

Use Cases:

  • Building administrative dashboards showing all users
  • Filtering users by organization for multi-tenant management
  • Monitoring user balances for usage-based billing
  • Searching for specific users by username
  • Generating user reports with pagination support

Full URL Example:

https://gate.zequenze.com/api/v1/user_token/?organization=5&balance=true&limit=25&offset=0

Parameters:

Parameter Type In Required Description
username string query No Filter users by exact username match
organization string query No Filter users belonging to specific organization ID
limit integer query No Number of results per page (default: 20)
offset integer query No Starting index for pagination (default: 0)
balance boolean query No Include remaining time balance in seconds in response

cURL Example:

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

Example Response:

{
  "count": 157,
  "next": "https://gate.zequenze.com/api/v1/user_token/?limit=10&offset=10&organization=5&balance=true",
  "previous": null,
  "results": [
    {
      "id": 123,
      "username": "john.doe",
      "external_id": "EXT_USER_789",
      "klass": "premium_user",
      "password": "****",
      "is_active": true,
      "organization": 5,
      "description": "Premium customer - Network Access",
      "date_joined": "2024-01-15T09:30:00Z",
      "last_login": "2024-03-10T14:22:00Z",
      "expiration": "2024-12-31T23:59:59Z",
      "profile": ["vpn_access", "high_bandwidth"],
      "user_time": 86400
    }
  ]
}

Response Codes:

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

POST /user_token/

Description: Creates a new user with AAA profile configuration. This endpoint handles user provisioning with optional external system integration, time quota assignment, and organizational membership setup.

Use Cases:

  • Provisioning new users from external systems
  • Creating users with specific service class assignments
  • Setting up users with predefined time quotas
  • Bulk user creation through automated scripts
  • Onboarding users with specific AAA profiles

Full URL Example:

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

Request Body Example:

{
  "username": "jane.smith",
  "password": "SecurePass123!",
  "email": "jane.smith@company.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "external_id": "HR_EMP_4567",
  "klass": "standard_user",
  "organization": 5,
  "description": "Standard employee - IT Department",
  "expiration": "2024-12-31T23:59:59Z",
  "is_active": true,
  "profile": ["basic_network", "email_access"],
  "avatar_url": "https://company.com/avatars/jane.smith.jpg"
}

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": "jane.smith",
    "password": "SecurePass123!",
    "email": "jane.smith@company.com",
    "organization": 5,
    "profile": ["basic_network", "email_access"],
    "is_active": true
  }'

Example Response:

{
  "id": 124,
  "username": "jane.smith",
  "external_id": "HR_EMP_4567",
  "klass": "standard_user",
  "password": "****",
  "email": "jane.smith@company.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "is_active": true,
  "organization": 5,
  "description": "Standard employee - IT Department",
  "date_joined": "2024-03-11T10:15:00Z",
  "first_login": null,
  "last_login": null,
  "expiration": "2024-12-31T23:59:59Z",
  "avatar_url": "https://company.com/avatars/jane.smith.jpg",
  "profile": ["basic_network", "email_access"]
}

Response Codes:

Status Description
201 Created - User successfully created
400 Bad Request - Invalid data or username already exists
401 Unauthorized - Invalid or missing Bearer token
403 Forbidden - Insufficient permissions to create users

GET /user_token/{id}/

Description: Retrieves detailed information for a specific user by their ID, including AAA profile data and optional balance information. This endpoint is perfect for user detail views, account management interfaces, and integration with external systems.

Use Cases:

  • Displaying user profile information in admin interfaces
  • Checking user balance and quota information
  • Retrieving user data for external system synchronization
  • Building user account management features
  • Monitoring individual user status and activity

Full URL Example:

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

Parameters:

Parameter Type In Required Description
id integer path Yes Unique user ID to retrieve
balance boolean query No Include remaining time balance in seconds

cURL Example:

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

Example Response:

{
  "id": 123,
  "username": "john.doe",
  "external_id": "EXT_USER_789",
  "klass": "premium_user",
  "password": "****",
  "is_active": true,
  "organization": 5,
  "description": "Premium customer - Network Access",
  "date_joined": "2024-01-15T09:30:00Z",
  "last_login": "2024-03-10T14:22:00Z",
  "expiration": "2024-12-31T23:59:59Z",
  "profile": ["vpn_access", "high_bandwidth", "priority_support"],
  "user_time": 259200
}

Response Codes:

Status Description
200 Success - Returns user details
401 Unauthorized - Invalid or missing Bearer token
404 Not Found - User ID does not exist
403 Forbidden - Insufficient permissions to access user

PUT /user_token/{id}/

Description: Completely updates a user's information, replacing all modifiable fields with new values. This endpoint requires sending all user data, even unchanged fields, making it suitable for full profile updates and bulk user data synchronization.

Use Cases:

  • Synchronizing complete user records from external systems
  • Performing full profile updates in admin interfaces
  • Updating users after organizational changes
  • Migrating user data between systems
  • Bulk updating user profiles with complete data sets

Full URL Example:

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

Request Body Example:

{
  "username": "john.doe.updated",
  "external_id": "EXT_USER_789_NEW",
  "klass": "enterprise_user",
  "password": "NewSecurePass456!",
  "is_active": true,
  "organization": 7,
  "description": "Enterprise customer - Updated profile",
  "expiration": "2025-06-30T23:59:59Z",
  "profile": ["vpn_access", "high_bandwidth", "priority_support", "admin_tools"],
  "user_time": 172800
}

cURL Example:

curl -X PUT "https://gate.zequenze.com/api/v1/user_token/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe.updated",
    "klass": "enterprise_user",
    "is_active": true,
    "organization": 7,
    "profile": ["vpn_access", "high_bandwidth", "priority_support"]
  }'

Example Response:

{
  "id": 123,
  "username": "john.doe.updated",
  "external_id": "EXT_USER_789_NEW",
  "klass": "enterprise_user",
  "password": "****",
  "is_active": true,
  "organization": 7,
  "description": "Enterprise customer - Updated profile",
  "date_joined": "2024-01-15T09:30:00Z",
  "last_login": "2024-03-10T14:22:00Z",
  "expiration": "2025-06-30T23:59:59Z",
  "profile": ["vpn_access", "high_bandwidth", "priority_support", "admin_tools"],
  "user_time": 172800
}

Response Codes:

Status Description
200 Success - User completely updated
400 Bad Request - Invalid data or validation errors
401 Unauthorized - Invalid or missing Bearer token
404 Not Found - User ID does not exist
403 Forbidden - Insufficient permissions to update user

PATCH /user_token/{id}/

Description: Partially updates specific user fields without affecting unchanged data. This endpoint is ideal for making targeted updates like changing user status, adding time balance, or modifying specific profile settings while preserving existing user information.

Use Cases:

  • Updating user active/inactive status
  • Adding or removing specific AAA profiles
  • Extending user expiration dates
  • Adjusting time quotas and balances
  • Making incremental changes to user accounts

Full URL Example:

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

Request Body Example:

{
  "is_active": false,
  "description": "Account suspended - Payment overdue",
  "user_time": 0,
  "profile": ["basic_access"]
}

cURL Example:

curl -X PATCH "https://gate.zequenze.com/api/v1/user_token/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false,
    "user_time": 0
  }'

Example Response:

{
  "id": 123,
  "username": "john.doe",
  "external_id": "EXT_USER_789",
  "klass": "premium_user",
  "password": "****",
  "is_active": false,
  "organization": 5,
  "description": "Account suspended - Payment overdue",
  "date_joined": "2024-01-15T09:30:00Z",
  "last_login": "2024-03-10T14:22:00Z",
  "expiration": "2024-12-31T23:59:59Z",
  "profile": ["basic_access"],
  "user_time": 0
}

Response Codes:

Status Description
200 Success - User partially updated
400 Bad Request - Invalid field values
401 Unauthorized - Invalid or missing Bearer token
404 Not Found - User ID does not exist
403 Forbidden - Insufficient permissions to modify user

DELETE /user_token/{id}/

Description: Permanently removes a user from the system. This action is irreversible and will delete all user data, tokens, and associated records. Use with caution and consider deactivating users instead of deletion for audit trail purposes.

Use Cases:

  • Removing test accounts from production systems
  • Cleaning up duplicate or invalid user accounts
  • Complying with data deletion requirements (GDPR)
  • Deprovisioning users who permanently leave organization
  • Bulk cleanup of expired or unused accounts

Full URL Example:

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

Parameters:

Parameter Type In Required Description
id integer path Yes Unique user ID to delete

cURL Example:

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

Response Codes:

Status Description
204 No Content - User successfully deleted
401 Unauthorized - Invalid or missing Bearer token
404 Not Found - User ID does not exist
403 Forbidden - Insufficient permissions to delete user
409 Conflict - User cannot be deleted due to existing dependencies

Common Use Cases

Use Case 1: ISP Customer Management

Manage internet service provider customers with time-based quotas and service tiers. Use GET /user_token/ to list customers by organization, POST /user_token/ to provision new customers, and PATCH /user_token/{id}/ to adjust quotas and service classes.

Use Case 2: Corporate Network Access Control

Control employee network access with expiration dates and AAA profiles. Create users with specific network profiles, monitor login activity, and automatically disable accounts when employees leave the organization.

Use Case 3: Multi-tenant SaaS User Management

Manage users across multiple client organizations with different service levels. Filter users by organization, assign appropriate AAA profiles based on subscription tiers, and track usage through time balances.

Use Case 4: External System Integration

Synchronize user data between your primary system and GATE API using external_id fields. Create and update users based on HR system changes, maintaining referential integrity across platforms.

Use Case 5: Prepaid Service Management

Implement prepaid internet or network services by managing user time balances. Create users with initial time quotas, monitor remaining balances, and automatically deactivate users when time expires.

Best Practices

  • Use Pagination Effectively: Always implement pagination for user lists using limit and offset parameters to avoid performance issues with large datasets
  • Implement Proper Filtering: Use organization and username filters to reduce API response sizes and improve application performance
  • Handle Time Balances Carefully: When working with user_time values, always specify the balance=true parameter to get accurate remaining quotas
  • Secure Password Handling: Never log or expose password fields; they're automatically masked in responses for security
  • Use PATCH for Targeted Updates: Prefer PATCH over PUT for single field updates to reduce bandwidth and avoid accidentally clearing fields
  • Implement Soft Deletion: Consider setting is_active=false instead of using DELETE for better audit trails and data recovery options
  • Monitor Expiration Dates: Regularly check user expiration dates and implement automated processes to handle expired accounts
  • Validate External IDs: When using external_id for system integration, ensure uniqueness and implement proper error handling for synchronization failures
Back to top