Skip to main content

User

The User API provides comprehensive user management functionalitycapabilities includingfor AAAthe (Authentication,GATE Authorization,system, and Accounting) profile information. These endpoints enableallowing you to create, retrieve, update, and delete users,users along with their AAA (Authentication, Authorization, Accounting) profile information. These endpoints support for both ID-based and username-based operationsoperations, making it flexible for flexibledifferent integration scenarios.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The User API category is designedthe core component for completemanaging user lifecycle managementaccounts within the GATE system. It provides dualfull CRUD (Create, Read, Update, Delete) operations for user management, with additional support for AAA profiles that define user permissions and access patterns - both ID-based and username-based operations - making it versatile for different integration approaches. Whether you're building a user management interface, synchronizing user data from external systems, or implementing automated user provisioning, these endpoints provide the necessary functionality.levels.

Key Features:

  • Complete CRUD Operations: Create, read, update, and delete users with full profile information
FlexibleDual Access PatternsMethods: Access users by either numeric ID or username stringfor maximum flexibility AAA Profile Integration: IncludesManage Authentication,authentication, Authorization,authorization, and Accountingaccounting profileprofiles alongside user data Organization FilteringSupport: SupportAssociate users with specific organizations for multi-tenant scenarios with organization-based user management PaginationExternal SupportSystem Integration: EfficientLink handlingusers ofto largeexternal systems using external_id and klass fields User Lifecycle Management: Track user datasetscreation, login history, and set expiration dates Filtering and Pagination: Efficiently retrieve user lists with limit/offsetadvanced paginationfiltering options

Common IntegrationUse Scenarios:Cases:

  • User directory synchronization from LDAP/Active Directory
Self-service user management portals Automated user provisioning for new employee onboarding Bulk user operations and maintenanceaccount tasksprovisioning Integration with externalexisting authenticationuser systemsdirectories (LDAP, Active Directory) Multi-tenant application user management Access control and permission management User activity tracking and reporting

Endpoints

GET /user/

Description: RetrieveRetrieves a paginated list of all users within the system, including their AAA profile information. This endpoint supports comprehensive filtering options.options Thisto endpointhelp isyou idealfind forspecific building user directory listings, implementing search functionality,users or performinggroups bulkof operationsusers acrossbased useron datasets.various criteria.

Use Cases:

  • Display alluser usersdirectories inor anadministration organization for administrative purposespanels
  • SearchBulk foruser specificmanagement users by username or organizationoperations
  • ExportIntegration with external systems requiring user data for reporting or compliance purposessynchronization
  • ImplementReporting and analytics on user selection interfaces in other applicationsbase

Full URL Example:

https://gate.zequenze.com/api/v1/user/?organization=engineering123&is_active=true&limit=2520&offset=0

Parameters:

Parameter Type In Required Description
id string query No Filter users by specific user ID
username string query No Filter users by username (supports partial matching)matches supported)
organization string query No Filter users belonging to a specificby organization ID
limit integer query No Number of results to return per page (default: 20, max: 100)20)
offset integer query No TheStarting initialposition index from which to returnfor results (for paginationpagination)

cURL Example:

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

Example Response:

{
  "count": 156,150,
  "next": "https://gate.zequenze.com/api/v1/user/?limit=2510&offset=25&organization=engineering"10",
  "previous": null,
  "results": [
    {
      "id": 42,1,
      "username": "john.smith"doe",
      "external_id": "AD_12345",
      "klass": "employee",
      "email": "john.smith@company.doe@company.com",
      "first_name": "John",
      "last_name": "Smith",
      "organization": "engineering"Doe",
      "is_active": true,
      "last_login"organization": 123,
      "description": "Senior Network Administrator",
      "date_joined": "2024-01-15T10:30:00Z",
      "first_login": "2024-01-15T14:22:30Z"00Z",
      "date_joined"last_login": "2023-08-12T09:2024-03-20T09:15:00Z",
      "groups"expiration": "2025-01-15T00:00:00Z",
      "avatar_url": "https://avatars.company.com/john.doe.jpg",
      "source_id": 5,
      "profile": ["developers"network_admin", "vpn_users"]vpn_user", "aaa_profile": {
        "role": "user",
        "department": "Software Engineering",
        "manager": "jane.doe",
        "access_level": "standard"
      }reporting_viewer"]
    }
  ]
}

Response Codes:

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

POST /user/

Description: CreateCreates a new user account in the system with complete profile information includingassociated AAA settings.profiles. This endpoint isallows essentialyou forto userprovision onboardingnew processes,users automatedwith provisioningall systems,necessary account information and administrativeaccess userpermissions creationin workflows.a single operation.

Use Cases:

  • Automated employeeUser onboarding fromand HRaccount systemsprovisioning
  • Self-registration portals for external users
BulkBatch user creation from CSVexternal importssystems API-drivenSelf-service useraccount provisioningcreation workflows Integration with HR systems for partnerautomatic organizationsaccount setup

Full URL Example:

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

Request Body Parameters:

Parameter Type In
Required Description datausername object bodystring Yes CompleteUnique username (150 chars max, alphanumeric and @/./+/-/:/|/_ only) password string No User password (will be hashed automatically) email string No Valid email address first_name string No User's first name last_name string No User's last name external_id string No Reference ID for external systems klass string No Service class reference is_active boolean No Whether user objectaccount is active (default: true) organization integer No Organization ID to associate user with description string No Additional user description expiration string No User expiration date (ISO 8601 format) avatar_url string No URL to user's avatar image profile array No Array of AAA profile and AAA informationshort-names

cURL Example:

curl -X POST "https://gate.zequenze.com/api/v1/user/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "sarah.johnson"jane.smith",
    "password": "SecurePassword123!",
    "email": "sarah.johnson@company.jane.smith@company.com",
    "first_name": "Sarah"Jane",
    "last_name": "Johnson"Smith",
    "external_id": "HR_67890",
    "klass": "contractor",
    "organization": 123,
    "marketing"description": "Network Security Specialist",
    "password"expiration": "SecureP@ssw0rd!"2024-12-31T23:59:59Z",
    "is_active": true,
    "groups"profile": ["marketing_team"security_admin", "vpn_users"vpn_user"],
    "aaa_profile": {
      "role": "user",
      "department": "Digital Marketing",
      "manager": "mike.wilson",
      "access_level": "standard"
    }
  }'

Example Response:

{
  "id": 157,25,
  "username": "sarah.johnson"jane.smith",
  "external_id": "HR_67890",
  "klass": "contractor",
  "email": "sarah.johnson@company.jane.smith@company.com",
  "first_name": "Sarah"Jane",
  "last_name": "Johnson",
  "organization": "marketing"Smith",
  "is_active": true,
  "last_login"organization": null,123,
  "description": "Network Security Specialist",
  "date_joined": "2024-01-16T10:03-20T10:30:45Z"00Z",
  "groups"first_login": null,
  "last_login": null,
  "expiration": "2024-12-31T23:59:59Z",
  "avatar_url": null,
  "profile": ["marketing_team"security_admin", "vpn_users"vpn_user"],
  "aaa_profile": {
    "role": "user",
    "department": "Digital Marketing",
    "manager": "mike.wilson",
    "access_level": "standard"
  }
}

Response Codes:

Status Description
201 Created - User successfully created
400 Bad Request - Invalid user data or validation errors
401 Unauthorized - Invalid or missing authenticationAPI token
403 Forbidden - Insufficient permissions to create users 409 Conflict - Username or email already exists

GET /user/username/{username}/

Description: RetrieveRetrieves detailed information for a specific user identified by their username. This endpoint is particularly useful when integratingyou withknow systemsthe thatusername primarilybut worknot with usernames rather thanthe numeric IDs.ID, which is common in username-based authentication systems.

Use Cases:

  • User profile lookups induring authentication flows
  • Username-based user verificationmanagement processes
Profile display in applications using username as primary identifierinterfaces Integration with external systems that reference users by username User self-service profile viewing

Full URL Example:

https://gate.zequenze.com/api/v1/user/username/john.smith/doe/

Path Parameters:

Parameter Type Required Description username string Yes The username of the user to retrieve

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/user/username/john.smith/doe/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 42,1,
  "username": "john.smith"doe",
  "external_id": "AD_12345",
  "klass": "employee",
  "email": "john.smith@company.doe@company.com",
  "first_name": "John",
  "last_name": "Smith",
  "organization": "engineering"Doe",
  "is_active": true,
  "last_login"organization": 123,
  "description": "Senior Network Administrator",
  "date_joined": "2024-01-15T10:30:00Z",
  "first_login": "2024-01-15T14:22:30Z"00Z",
  "date_joined"last_login": "2023-08-12T09:2024-03-20T09:15:00Z",
  "groups"expiration": "2025-01-15T00:00:00Z",
  "avatar_url": "https://avatars.company.com/john.doe.jpg",
  "source_id": 5,
  "profile": ["developers"network_admin", "vpn_users"vpn_user", "senior_staff"reporting_viewer"],
  "aaa_profile": {
    "role": "senior_developer",
    "department": "Software Engineering",
    "manager": "jane.doe",
    "access_level": "elevated",
    "security_clearance": "confidential"
  }
}

Response Codes:

Status Description
200 Success - Returns user details
401 Unauthorized - Invalid or missing authenticationAPI token
403 Forbidden - Insufficient permissions to view user 404 Not Found - Username does not exist

PUT /user/username/{username}/

Description: Completely updateupdates a user's profile information usingby theirusername, usernamereplacing asall the identifier. This operation replaces the entire user recordfields with the provided data,data. makingThis itis suitablea forfull comprehensiveupdate profileoperation updates.that requires all user fields to be specified in the request body.

Use Cases:

  • Complete user profile synchronizationupdates from external HRsystems
systemsBulk user data synchronization Administrative profileuser overhaulsaccount management Migration orbetween datauser correctionmanagement operations Bulk profile updates via automated scriptssystems

Full URL Example:

https://gate.zequenze.com/api/v1/user/username/john.smith/doe/

cURL Example:

curl -X PUT "https://gate.zequenze.com/api/v1/user/username/john.smith/doe/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.smith"doe",
    "email": "j.smith@company.doe@company.com",
    "first_name": "Jonathan"John",
    "last_name": "Smith"Doe",
    "organization"external_id": "engineering"AD_12345_UPDATED",
    "klass": "senior_employee",
    "is_active": true,
    "groups"organization": 123,
    "description": "Lead Network Administrator",
    "expiration": "2025-06-30T23:59:59Z",
    "profile": ["developers"network_admin", "vpn_users"vpn_user", "team_leads"]reporting_admin", "aaa_profile": {
      "role": "team_lead",
      "department": "Software Engineering",
      "manager": "jane.doe",
      "access_level": "elevated"
    }security_viewer"]
  }'

Response Codes:

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

PATCH /user/username/{username}/

Description: Partially update specific fields ofupdates a user's profileinformation usingby theirusername, username. This endpoint allowsallowing you to modify only thespecific fields without affecting others. This is more efficient than PUT when you specifyonly whileneed leavingto otherchange usera datafew unchanged, perfect for targeted updates.attributes.

Use Cases:

  • UpdateUpdating specific profileuser fieldsattributes like(email, emailphone, or departmentdepartment)
  • ChangeStatus changes (activate/deactivate users)
Profile adjustments without full data reload Incremental user statusdata (activate/deactivate) without affecting other data Modify group memberships or access levels Implement granular profile editing interfacesupdates

Full URL Example:

https://gate.zequenze.com/api/v1/user/username/john.smith/doe/

cURL Example:

curl -X PATCH "https://gate.zequenze.com/api/v1/user/username/john.smith/doe/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.smith.new@company.doe.updated@company.com",
    "aaa_profile": {
      "access_level"description": "admin"Senior }Network Administrator - Updated Role",
    "profile": ["network_admin", "vpn_user", "reporting_viewer", "audit_viewer"]
  }'

Response Codes:

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

DELETE /user/username/{username}/

Description: Permanently deletedeletes a user account usingby their username as the identifier.username. This operation is irreversible and will removeremoves all user data and associated AAA profileprofiles information.from the system and cannot be undone.

Use Cases:

  • Employee offboarding processes
  • Account cleanup forand inactivemaintenance
Compliance with data retention policies Removing test or testtemporary users Compliance-driven data removal requests Automated account lifecycle managementaccounts

Full URL Example:

https://gate.zequenze.com/api/v1/user/username/john.smith/doe/

cURL Example:

curl -X DELETE "https://gate.zequenze.com/api/v1/user/username/john.smith/doe/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Codes:

Status Description
204 No Content - User successfully deleted
401 Unauthorized - Invalid or missing authenticationAPI token
403 Forbidden - Insufficient permissions to delete user 404 Not Found - Username does not exist

GET /user/{id}/

Description: RetrieveRetrieves detailed information for a specific user identified by their numeric ID. This endpoint is optimalideal forwhen applicationsyou thathave primarilythe workuser's withID from previous API calls or database IDs and need consistent, immutable user references.

Use Cases:

  • Database-drivenRetrieving applicationsuser details with known ID from database
Following references from other API responses Administrative interfaces using numeric user IDsidentifiers ForeignSystem-to-system keyintegrations relationshipsusing inID-based related data systems Audit trails and logging systems Performance-optimized user lookupsreferences

Full URL Example:

https://gate.zequenze.com/api/v1/user/42/123/

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/user/42/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 42,
  "username": "john.smith",
  "email": "john.smith@company.com",
  "first_name": "John",
  "last_name": "Smith",
  "organization": "engineering",
  "is_active": true,
  "last_login": "2024-01-15T14:22:30Z",
  "date_joined": "2023-08-12T09:15:00Z",
  "groups": ["developers", "vpn_users"],
  "aaa_profile": {
    "role": "user",
    "department": "Software Engineering",
    "manager": "jane.doe",
    "access_level": "standard"
  }
}

Response Codes:

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

PUT /user/{id}/

Description: Completely updateupdates a user's profile information usingby theirID, replacing all fields with the provided data. Similar to the username-based PUT endpoint but uses numeric ID.ID Thisfor operation replaces the entire user record, providing a reliable way to synchronize complete user profiles in ID-based systems.identification.

Full URL Example:

https://gate.zequenze.com/api/v1/user/42/123/

cURL Example:

curl -X PUT "https://gate.zequenze.com/api/v1/user/42/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.smith"doe.updated",
    "email": "john.smith.updated@company.com",
    "first_name": "John",
    "last_name": "Smith",
    "organization": "engineering"Doe",
    "is_active": true,
    "groups"organization": 123,
    "profile": ["developers"network_admin", "vpn_users", "architects"security_admin"],
    "aaa_profile": {
      "role": "senior_developer",
      "department": "Software Engineering",
      "manager": "jane.doe",
      "access_level": "elevated"
    }
  }'

Response Codes:

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

PATCH /user/{id}/

Description: Partially update specific fields ofupdates a user's profileinformation usingby theirID, numericallowing ID.modification of specific fields only. This endpointprovides enablesthe precise,same field-levelpartial updatesupdate whilefunctionality maintainingas datathe integrityusername-based forPATCH unchanged fields.endpoint.

Full URL Example:

https://gate.zequenze.com/api/v1/user/42/123/

cURL Example:

curl -X PATCH "https://gate.zequenze.com/api/v1/user/42/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false,
    "aaa_profile": {
      "access_level"description": "Account temporarily suspended",
    }"expiration": "2024-06-30T23:59:59Z"
  }'

Response Codes:

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

DELETE /user/{id}/

Description: Permanently deletedeletes a user account using their numericby ID. This operation provideshas athe reliablesame wayeffect toas removethe usersusername-based inDELETE systemsbut thatuses primarilynumeric workID withfor database IDs.identification.

Full URL Example:

https://gate.zequenze.com/api/v1/user/42/123/

cURL Example:

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

Response Codes:

Status Description
204 No Content - User successfully deleted
401 Unauthorized - Invalid or missing authenticationAPI token
403 Forbidden - Insufficient permissions to delete user 404 Not Found - User ID does not exist

Common Use Cases

Use Case 1: Employee Onboarding AutomationWorkflow

IntegrateWhen a new employee joins, create their account with appropriate AAA profiles, set expiration based on contract length, and link to external HR systems tousing automaticallythe createexternal_id userfield.

accounts

Endpoints when new employees join. UseUsed: POST /user/ to create accounts with complete AAA profiles, then use, PATCH /user/username/{username}/ to update group memberships as roles are assigned.

Use Case 2: User Directory Synchronization

Regularly sync user datausers from external directorydirectories services(LDAP/AD) by listing all users, comparing with external data, and updating changed information using partial updates.

Endpoints Used: GET /user/ to retrieve current users, then use, PUTPATCH /user/{id}/, operationsPOST to/user/

update

Use existingCase 3: Access Management and Compliance

Monitor user access by retrieving user profiles, updating AAA profiles orbased POSTon torole createchanges, newand onessetting asexpiration needed.dates for temporary access.

Self-Service

Endpoints Profile Management

Build user portals where individuals can update their own information usingUsed:

GET /user/username/{username}/, PATCH /user/{id}/

Use Case 4: Automated Account Lifecycle Management

Implement automated processes to displaydeactivate currentexpired dataaccounts, remove inactive users, and PATCH operations to save specific field changes.

Compliance and Audit Workflows

Use the dual access patterns (ID and username) to maintain consistent audit trails while supporting both human-readable usernames and immutable ID references forgenerate compliance reporting.reports based on user data.

Bulk

Endpoints OperationsUsed: and Maintenance

Leverage the list endpoint with pagination (GET /user/), PATCH /user/{id}/, DELETE /user/{id}/

Use Case 5: Self-Service User Management

Allow users to processview large user datasets efficiently, combined with batchand update operationstheir forown maintenanceprofile tasksinformation likethrough groupa membershipweb changesinterface orwhile policyrestricting updates.access to administrative fields.

Endpoints Used: GET /user/username/{username}/, PATCH /user/username/{username}/

Best Practices

  • Choose the Right Identifier: Use username-basedPagination endpoints for user-facing applications and ID-based endpoints for backend systems requiring stable references

Implement Proper PaginationEffectively: Always useimplement appropriatepagination limitwhen valuesretrieving (recommended:user 25-50 users per page)lists to avoid performance issues with large user datasetsbases. Start with reasonable page sizes (20-50 users).

HandleImplement PartialProper UpdatesError CarefullyHandling: Check response codes and handle common errors like 404 (user not found) and 409 (username conflicts) gracefully in your applications.

Choose the Right Endpoint: Use PATCHusername-based operationsendpoints when integrating with username-centric systems, and ID-based endpoints for single-fielddatabase-driven updates to avoid overwriting data accidentally, reserve PUT for complete profile replacements

Validate Before Creation: Ensure usernames and email addresses are unique and follow organizational policies before creating users via POST /user/applications.

ImplementSecure SoftPassword DeletionHandling: ConsiderNever log or store passwords in plaintext. The API handles password hashing automatically, but ensure secure transmission using PATCHHTTPS.

to set is_active: false instead of DELETE operations to preserve audit trails and data relationships

CacheAAA UserProfile Data AppropriatelyManagement: UserCarefully manage AAA profiles as they directly impact user permissions. Implement approval workflows for profile data changes infrequentlyin -production implementenvironments.

reasonable caching strategies to reduce API calls

MonitorData Rate LimitsConsistency: BulkWhen operationsusing shouldexternal_id implementfor system integration, ensure these IDs remain consistent across all systems to maintain proper user linking.

Monitoring and Auditing: Implement logging for all user management operations, especially creation and deletion, to maintain security audit trails.

Rate Limiting: Be mindful of API rate limits when performing bulk operations. Implement appropriate delays and respectretry APIlogic ratefor limitinglarge-scale touser maintainmanagement systemtasks.

stability
Back to top