Skip to main content

User Token

The User Token API provides comprehensive user management capabilitiesfunctionality includingwith integrated AAA (Authentication, Authorization, and Accounting) profile information.support. These endpoints allow you to create, retrieve, update, and delete userusers accountswhile along withmanaging their associatedauthentication token-credentials, time-based authentication credentialsbalances, and usageaccess tracking.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 user accountsusers in systems that require token-time-based authenticationaccess control, quota management, and usageorganizational tracking.segmentation. This API category is particularly useful for:

  • UserNetwork AccountAccess Control: Managing user credentials and time quotas for network services
Service Provider Management: Create and maintainTracking 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 consumptionservice inclass time-based systemsassignments Multi-tenant OperationsOrganizations: Filter and manageOrganizing users across different organizations with custom profiles External System Integration: Synchronizing user data with external databases using external_id references

TheseKey endpointsfeatures workinclude:

together
    Time-based Quotas: Track user time balances in seconds for usage-based services AAA Profile Integration: Assign authentication, authorization, and accounting profiles to provideusers a completeExpiration Management: Set automatic user lifecycleexpiration managementdates system. TheOrganizational listSegmentation: andGroup 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 meteredusers by duration.

    Key concepts include user tokens that represent time-based access credits, organization-based user segmentationorganization for multi-tenant environments,scenarios

    External System Sync: Link users to external systems via external_id for seamless integration

    The API supports both individual user operations and real-timebulk balancelisting trackingwith advanced filtering capabilities, making it suitable for usageboth monitoring.administrative interfaces and automated user provisioning systems.

    Endpoints

    GET /user_token/

    Description: Retrieves a paginated list of all users with their AAA profile information.information and optional balance data. This endpoint supportsis filteringessential byfor usernamebuilding user management interfaces, generating reports, and organization, making it ideal for administrative dashboards andmonitoring user searchaccounts functionality.across your organization.

    Use Cases:

    • DisplayBuilding administrative dashboards showing all users in an administrative interface
    • SearchFiltering users by organization for multi-tenant management
    Monitoring user balances for usage-based billing Searching for specific users by username Filter users by organization in multi-tenant systems MonitorGenerating user tokenreports balanceswith acrosspagination your systemsupport

    Full URL Example:

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

    Parameters:

    Parameter Type In Required Description
    username string query No Filter results to show only users matching thisby exact username match
    organization string query No Filter results to show only users belonging to thisspecific organization ID
    limit integer query No Number of results to return per page (default: 20, max: 100)20)
    offset integer query No Starting positionindex for resultspagination (useddefault: for pagination)0)
    balance boolean query No When true, includesInclude remaining time balance in seconds forin each userresponse

    cURL Example:

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

    Example Response:

    {
  "count": 45,157,
  "next": "https://gate.zequenze.com/api/v1/user_token/?limit=10&offset=10"10&organization=5&balance=true",
  "previous": null,
  "results": [
    {
      "id": 1,123,
      "username": "john_doe"john.doe",
      "email"external_id": "john@acmecorp.com"EXT_USER_789",
      "organization"klass": "acme_corp"premium_user",
      "password": "****",
      "is_active": true,
      "token"organization": 5,
      "description": "tok_abc123def456"Premium customer - Network Access",
      "balance_seconds": 86400,
      "created_at"date_joined": "2024-01-15T10:15T09:30:00Z",
      "last_login": "2024-01-20T14:03-10T14:22:00Z",
      "expiration": "2024-12-31T23:59:59Z",
      "profile": {
        ["max_sessions": 2,
        "access_level": "premium"
      }
    },
    {
      "id": 2,
      "username": "jane_smith"vpn_access", "email": "jane@acmecorp.com"high_bandwidth"],
      "organization"user_time": "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"
      }86400
    }
  ]
}

    Response Codes:

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

    POST /user_token/

    Description: Creates a new user account with AAA profile information and generates an associated authentication token.configuration. This endpoint is essential forhandles user onboardingprovisioning with optional external system integration, time quota assignment, and accountorganizational provisioningmembership workflows.setup.

    Use Cases:

    • RegisterProvisioning new users infrom yourexternal systemsystems
    Creating users with specific service class assignments Setting up users with predefined time quotas Bulk user creation forthrough organizationautomated onboardingscripts ProvisionOnboarding accountsusers with specific accessAAA levels and time allowances Create temporary access accounts with predefined expirationprofiles

    Full URL Example:

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

    Parameters:Request Body Example:

    {
  "username": "jane.smith",
  Parameter"password": Type"SecurePass123!",
  In"email": Required"jane.smith@company.com",
  Description"first_name": "Jane",
  "last_name": "Smith",
  "external_id": data"HR_EMP_4567",
  object"klass": body"standard_user",
  Yes"organization": JSON5,
  object"description": containing"Standard useremployee information- andIT profileDepartment",
  settings"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": "new_user"jane.smith",
    "password": "SecurePass123!",
    "email": "newuser@company.jane.smith@company.com",
    "organization": 5,
    "tech_startup"profile": ["basic_network", "email_access"],
    "is_active": true,
    "initial_balance_seconds": 172800,
    "profile": {
      "max_sessions": 3,
      "access_level": "premium"
    }true
  }'

    Example Response:

    {
  "id": 15,124,
  "username": "new_user"jane.smith",
  "external_id": "HR_EMP_4567",
  "klass": "standard_user",
  "password": "****",
  "email": "newuser@company.jane.smith@company.com",
  "organization"first_name": "tech_startup"Jane",
  "last_name": "Smith",
  "is_active": true,
  "token"organization": 5,
  "description": "tok_new456user789"Standard employee - IT Department",
  "balance_seconds": 172800,
  "created_at"date_joined": "2024-01-21T16:30: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", "max_sessions": 3,
    "access_level": "premium"
  }email_access"]
}

    Response Codes:

    Status Description
    201 Created - User successfully created with token
    400 Bad Request - Invalid data providedor username already exists
    401 Unauthorized - Invalid or missing APIBearer token
    409403 ConflictForbidden - UsernameInsufficient alreadypermissions existsto create users

    GET /user_token/{id}/

    Description: Retrieves detailed information for a specific user by their ID, including AAA profile data and optionallyoptional theirbalance current token balance.information. This endpoint is perfect for user profiledetail pagesviews, account management interfaces, and accountintegration statuswith checks.external systems.

    Use Cases:

    • DisplayDisplaying user profile information in admin interfaces
    • CheckChecking current tokenuser balance forand aquota specific userinformation
    • RetrieveRetrieving user detailsdata for administrativeexternal reviewsystem synchronization
    • ValidateBuilding user account management features
    Monitoring individual user status beforeand granting accessactivity

    Full URL Example:

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

    Parameters:

    Parameter Type In Required Description
    id integer path Yes Unique identifieruser of the userID to retrieve
    balance boolean query No Include currentremaining remainingtime balance in seconds

    cURL Example:

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

    Example Response:

    {
  "id": 15,123,
  "username": "new_user"john.doe",
  "email"external_id": "newuser@company.com"EXT_USER_789",
  "organization"klass": "tech_startup"premium_user",
  "password": "****",
  "is_active": true,
  "token"organization": 5,
  "description": "tok_new456user789"Premium customer - Network Access",
  "balance_seconds": 158400,
  "created_at"date_joined": "2024-01-21T16:15T09:30:00Z",
  "last_login": "2024-01-22T08:15:03-10T14:22:00Z",
  "expiration": "2024-12-31T23:59:59Z",
  "profile": {
    ["max_sessions": 3,
    "access_level": "premium"vpn_access", "total_usage_seconds"high_bandwidth", "priority_support"],
  "user_time": 14400,
    "last_activity": "2024-01-22T12:30:00Z"
  }259200
}

    Response Codes:

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

    PUT /user_token/{id}/

    Description: Completely updates a user's informationinformation, andreplacing AAAall profilemodifiable data.fields with new values. This endpoint replacesrequires sending all updatable fields with the provideduser data, even unchanged fields, making it idealsuitable for comprehensivefull profile updates and bulk user profiledata updates.synchronization.

    Use Cases:

    • UpdateSynchronizing complete user profilerecords informationfrom completelyexternal systems
    • ChangePerforming organizationfull assignmentprofile updates in admin interfaces
    • ModifyUpdating accessusers levelsafter andorganizational session limitschanges
    • ResetMigrating user tokensdata andbetween balancessystems
    Bulk updating user profiles with complete data sets

    Full URL Example:

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

    Parameters:Request Body Example:

    {
  "username": "john.doe.updated",
  Parameter"external_id": Type"EXT_USER_789_NEW",
  In"klass": Required"enterprise_user",
  Description"password": "NewSecurePass456!",
  "is_active": true,
  "organization": id7,
  integer"description": path"Enterprise Yescustomer Unique- identifierUpdated ofprofile",
  the"expiration": user"2025-06-30T23:59:59Z",
  to"profile": update["vpn_access", "high_bandwidth", "priority_support", data"admin_tools"],
  object"user_time": body172800
Yes}
Complete user data object with all fields to update

    cURL Example:

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

    Example Response:

    {
  "id": 15,123,
  "username": "updated_user"john.doe.updated",
  "email"external_id": "updated@company.com"EXT_USER_789_NEW",
  "organization"klass": "enterprise_corp"enterprise_user",
  "password": "****",
  "is_active": true,
  "token"organization": 7,
  "description": "tok_new456user789"Enterprise customer - Updated profile",
  "balance_seconds": 259200,
  "created_at"date_joined": "2024-01-21T16:15T09:30:00Z",
  "updated_at": "2024-01-23T10:45:00Z",
  "last_login": "2024-01-22T08:15:03-10T14:22:00Z",
  "expiration": "2025-06-30T23:59:59Z",
  "profile": {["vpn_access", "max_sessions"high_bandwidth", "priority_support", "admin_tools"],
  "user_time": 5,
    "access_level": "enterprise"
  }172800
}

    Response Codes:

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

    PATCH /user_token/{id}/

    Description: Partially updates specific user fields of a user's profile without affecting otherunchanged data. This endpoint is perfectideal for making targeted changesupdates like updatingchanging emailuser addresses,status, adjustingadding balances,time balance, or modifying specific profile settings.settings while preserving existing user information.

    Use Cases:

    • UpdateUpdating onlyuser active/inactive status
    Adding or removing specific userAAA fields (email, balance, etc.)profiles AddExtending user expiration dates Adjusting time quotas and balances Making incremental changes to user token balance Toggle user active status Modify individual profile settingsaccounts

    Full URL Example:

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

    Parameters:Request Body Example:

    {
  "is_active": false,
  Parameter"description": Type"Account Insuspended Required- DescriptionPayment overdue",
  "user_time": 0,
  "profile": id["basic_access"]
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/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "balance_seconds"is_active": 345600,false,
    "profile"user_time": {
      "max_sessions": 4
    }0
  }'

    Example Response:

    {
  "id": 15,123,
  "username": "updated_user"john.doe",
  "email"external_id": "updated@company.com"EXT_USER_789",
  "organization"klass": "enterprise_corp"premium_user",
  "password": "****",
  "is_active": true,false,
  "token"organization": 5,
  "description": "tok_new456user789"Account suspended - Payment overdue",
  "balance_seconds": 345600,
  "created_at"date_joined": "2024-01-21T16:15T09:30:00Z",
  "updated_at": "2024-01-23T14:20:00Z",
  "last_login": "2024-01-22T08:15:03-10T14:22:00Z",
  "expiration": "2024-12-31T23:59:59Z",
  "profile": {["basic_access"],
  "max_sessions"user_time": 4,
    "access_level": "enterprise"
  }0
}

    Response Codes:

    Status Description
    200 Success - User partially updated
    400 Bad Request - Invalid datafield providedvalues
    401 Unauthorized - Invalid or missing APIBearer token
    404 Not Found - User with specified ID does not exist
    403 Forbidden - Insufficient permissions to modify user

    DELETE /user_token/{id}/

    Description: Permanently removes a user account and associated token from the system. This action is irreversible and will immediately revokedelete all accessuser data, tokens, and associated records. Use with caution and consider deactivating users instead of deletion for theaudit specifiedtrail user.purposes.

    Use Cases:

    • RemoveRemoving inactivetest accounts from production systems
    Cleaning up duplicate or expiredinvalid user accounts Clean up test accounts ComplyComplying with data deletion requestsrequirements (GDPR) Revoke access for terminatedDeprovisioning users who permanently leave organization Bulk cleanup of expired or unused accounts

    Full URL Example:

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

    Parameters:

    Parameter Type In Required Description
    id integer path Yes Unique identifieruser of the userID to delete

    cURL Example:

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

    Response Codes:

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

    Common Use Cases

    UserUse OnboardingCase and1: ISP Customer Management

    CreateManage newinternet userservice accountsprovider customers with appropriatetime-based token balancesquotas and organizationservice assignments.tiers. Use theGET /user_token/ to list customers by organization, POST endpoint/user_token/ to provision accounts,new thencustomers, GETand PATCH /user_token/{id}/ to verifyadjust creationquotas and monitorservice initial usage patterns.classes.

    BalanceUse MonitoringCase 2: Corporate Network Access Control

    Control employee network access with expiration dates and Top-upsAAA

    Regularlyprofiles. checkCreate user token balances using the GET endpointsusers with thespecific balancenetwork parameter.profiles, Usemonitor PATCHlogin toactivity, addand timeautomatically to userdisable accounts when theyemployees purchaseleave additionalthe credits or need balance adjustments.organization.

    Organization-basedUse Case 3: Multi-tenant SaaS User AdministrationManagement

    Manage users across multiple client organizations with different service levels. Filter users by organizationorganization, 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 theexternal_id listfields. endpointCreate toand manageupdate multi-tenantusers environments.based Thison isHR particularlysystem usefulchanges, formaintaining servicereferential providersintegrity managingacross multiple client organizations.platforms.

    AccountUse LifecycleCase 5: Prepaid Service Management

    TrackImplement prepaid internet or network services by managing user activitytime frombalances. creationCreate tousers deletion.with Useinitial thetime read endpoint toquotas, monitor usageremaining patterns, update profiles as needed,balances, and ultimatelyautomatically delete inactive accounts to maintain system hygiene.

    Bulk Operations and Reporting

    Combine the list endpoint with pagination to process alldeactivate users inwhen batchestime for reporting, billing, or maintenance operations. The organization and balance filters help create targeted reports.expires.

    Best Practices

    • Use Pagination Effectively: Always useimplement pagination for user lists using 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.

      datasets

    • BalanceImplement MonitoringProper Filtering: IncludeUse theorganization balanceand parameterusername infilters GETto requestsreduce onlyAPI whenresponse yousizes needand currentimprove usageapplication data, as this may add processing overhead for real-time calculations.

      performance

    • ErrorHandle HandlingTime Balances Carefully: Always check for 404 errors whenWhen working with specificuser_time uservalues, IDs,always andspecify implementthe properbalance=true retryparameter logicto forget networkaccurate timeouts.remaining Handle 409 conflicts gracefully during user creation.

      quotas

    • SecuritySecure Password Handling: Never log or expose userpassword tokensfields; they're automatically masked in client-side code. Implement proper token rotation policies and monitorresponses for unusual usage patterns that might indicate token compromise.

      security

    • PerformanceUse PATCH for Targeted Updates: UsePrefer 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 PUTusing DELETE for smallbetter updatesaudit totrails minimizeand data transferrecovery and processing time. Cache user profile data when possible to reduce API calls. options

    DataMonitor ConsistencyExpiration Dates: Regularly check user expiration dates and implement automated processes to handle expired accounts

    Validate External IDs: When updatingusing userexternal_id organizationsfor orsystem access levels,integration, ensure youruniqueness applicationand logicimplement accountsproper error handling for anysynchronization active sessions that might be affected by the changes. failures
    Back to top