Skip to main content

User

The User API provides comprehensive user management functionality including AAA (Authentication, Authorization, and Accounting) profile information. These endpoints enable you to create, retrieve, update, and delete users, with support for both ID-based and username-based operations for flexible 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 designed for complete user lifecycle management within the GATE system. It provides dual 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.

Key Features:

  • Complete CRUD Operations: Create, read, update, and delete users with full profile information
  • Flexible Access Patterns: Access users by either numeric ID or username string
  • AAA Profile Integration: Includes Authentication, Authorization, and Accounting profile data
  • Organization Filtering: Support for multi-tenant scenarios with organization-based user management
  • Pagination Support: Efficient handling of large user datasets with limit/offset pagination

Common Integration Scenarios:

  • User directory synchronization from LDAP/Active Directory
  • Self-service user management portals
  • Automated user provisioning for new employee onboarding
  • Bulk user operations and maintenance tasks
  • Integration with external authentication systems

Endpoints

GET /user/

Description: Retrieve a paginated list of users with comprehensive filtering options. This endpoint is ideal for building user directory listings, implementing search functionality, or performing bulk operations across user datasets.

Use Cases:

  • Display all users in an organization for administrative purposes
  • Search for specific users by username or organization
  • Export user data for reporting or compliance purposes
  • Implement user selection interfaces in other applications

Full URL Example:

https://gate.zequenze.com/api/v1/user/?organization=engineering&limit=25&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)
organization string query No Filter users belonging to a specific organization
limit integer query No Number of results to return per page (default: 20, max: 100)
offset integer query No The initial index from which to return results for pagination

cURL Example:

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

Example Response:

{
  "count": 156,
  "next": "https://gate.zequenze.com/api/v1/user/?limit=25&offset=25&organization=engineering",
  "previous": null,
  "results": [
    {
      "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 paginated list of users
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - Insufficient permissions to list users

POST /user/

Description: Create a new user with complete profile information including AAA settings. This endpoint is essential for user onboarding processes, automated provisioning systems, and administrative user creation workflows.

Use Cases:

  • Automated employee onboarding from HR systems
  • Self-registration portals for external users
  • Bulk user creation from CSV imports
  • API-driven user provisioning for partner organizations

Full URL Example:

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

Parameters:

Parameter Type In Required Description
data object body Yes Complete user object with profile and AAA information

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",
    "email": "sarah.johnson@company.com",
    "first_name": "Sarah",
    "last_name": "Johnson",
    "organization": "marketing",
    "password": "SecureP@ssw0rd!",
    "is_active": true,
    "groups": ["marketing_team", "vpn_users"],
    "aaa_profile": {
      "role": "user",
      "department": "Digital Marketing",
      "manager": "mike.wilson",
      "access_level": "standard"
    }
  }'

Example Response:

{
  "id": 157,
  "username": "sarah.johnson",
  "email": "sarah.johnson@company.com",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "organization": "marketing",
  "is_active": true,
  "last_login": null,
  "date_joined": "2024-01-16T10:30:45Z",
  "groups": ["marketing_team", "vpn_users"],
  "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 authentication token
403 Forbidden - Insufficient permissions to create users
409 Conflict - Username or email already exists

GET /user/username/{username}/

Description: Retrieve detailed information for a specific user identified by their username. This endpoint is particularly useful when integrating with systems that primarily work with usernames rather than numeric IDs.

Use Cases:

  • User profile lookups in authentication flows
  • Username-based user verification processes
  • Profile display in applications using username as primary identifier
  • Integration with external systems that reference users by username

Full URL Example:

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

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/user/username/john.smith/" \
  -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", "senior_staff"],
  "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 authentication token
403 Forbidden - Insufficient permissions to view user
404 Not Found - Username does not exist

PUT /user/username/{username}/

Description: Completely update a user's profile information using their username as the identifier. This operation replaces the entire user record with the provided data, making it suitable for comprehensive profile updates.

Use Cases:

  • Complete profile synchronization from external HR systems
  • Administrative profile overhauls
  • Migration or data correction operations
  • Bulk profile updates via automated scripts

Full URL Example:

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

cURL Example:

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

Response Codes:

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

PATCH /user/username/{username}/

Description: Partially update specific fields of a user's profile using their username. This endpoint allows you to modify only the fields you specify while leaving other user data unchanged, perfect for targeted updates.

Use Cases:

  • Update specific profile fields like email or department
  • Change user status (activate/deactivate) without affecting other data
  • Modify group memberships or access levels
  • Implement granular profile editing interfaces

Full URL Example:

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

cURL Example:

curl -X PATCH "https://gate.zequenze.com/api/v1/user/username/john.smith/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.smith.new@company.com",
    "aaa_profile": {
      "access_level": "admin"
    }
  }'

Response Codes:

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

DELETE /user/username/{username}/

Description: Permanently delete a user account using their username as the identifier. This operation is irreversible and will remove all user data and associated AAA profile information.

Use Cases:

  • Employee offboarding processes
  • Account cleanup for inactive or test users
  • Compliance-driven data removal requests
  • Automated account lifecycle management

Full URL Example:

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

cURL Example:

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

Response Codes:

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

GET /user/{id}/

Description: Retrieve detailed information for a specific user identified by their numeric ID. This endpoint is optimal for applications that primarily work with database IDs and need consistent, immutable user references.

Use Cases:

  • Database-driven applications using numeric user IDs
  • Foreign key relationships in related data systems
  • Audit trails and logging systems
  • Performance-optimized user lookups

Full URL Example:

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

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/user/42/" \
  -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 authentication token
403 Forbidden - Insufficient permissions to view user
404 Not Found - User ID does not exist

PUT /user/{id}/

Description: Completely update a user's profile information using their numeric ID. This operation replaces the entire user record, providing a reliable way to synchronize complete user profiles in ID-based systems.

Full URL Example:

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

cURL Example:

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

Response Codes:

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

PATCH /user/{id}/

Description: Partially update specific fields of a user's profile using their numeric ID. This endpoint enables precise, field-level updates while maintaining data integrity for unchanged fields.

Full URL Example:

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

cURL Example:

curl -X PATCH "https://gate.zequenze.com/api/v1/user/42/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false,
    "aaa_profile": {
      "access_level": "suspended"
    }
  }'

Response Codes:

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

DELETE /user/{id}/

Description: Permanently delete a user account using their numeric ID. This operation provides a reliable way to remove users in systems that primarily work with database IDs.

Full URL Example:

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

cURL Example:

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

Response Codes:

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

Common Use Cases

Employee Onboarding Automation

Integrate with HR systems to automatically create user accounts when new employees join. Use POST /user/ to create accounts with complete AAA profiles, then use PATCH /user/username/{username}/ to update group memberships as roles are assigned.

User Directory Synchronization

Regularly sync user data from external directory services using GET /user/ to retrieve current users, then use PUT operations to update existing profiles or POST to create new ones as needed.

Self-Service Profile Management

Build user portals where individuals can update their own information using GET /user/username/{username}/ to display current data 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 for compliance reporting.

Bulk Operations and Maintenance

Leverage the list endpoint with pagination (GET /user/) to process large user datasets efficiently, combined with batch update operations for maintenance tasks like group membership changes or policy updates.

Best Practices

  • Choose the Right Identifier: Use username-based endpoints for user-facing applications and ID-based endpoints for backend systems requiring stable references
  • Implement Proper Pagination: Always use appropriate limit values (recommended: 25-50 users per page) to avoid performance issues with large user datasets
  • Handle Partial Updates Carefully: Use PATCH operations for single-field 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/
  • Implement Soft Deletion: Consider using PATCH to set is_active: false instead of DELETE operations to preserve audit trails and data relationships
  • Cache User Data Appropriately: User profile data changes infrequently - implement reasonable caching strategies to reduce API calls
  • Monitor Rate Limits: Bulk operations should implement appropriate delays and respect API rate limiting to maintain system stability
Back to top