Skip to main content

User

The User API provides comprehensive user management capabilities for the GATE system, allowing you to create, retrieve, update, and delete users along with their AAA (Authentication, Authorization, Accounting) profile information. These endpoints support both ID-based and username-based operations, making it flexible for different 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 is the core component for managing user accounts within the GATE system. It provides full CRUD (Create, Read, Update, Delete) operations for user management, with additional support for AAA profiles that define user permissions and access levels.

Key Features:

  • Dual Access Methods: Access users by either numeric ID or username for maximum flexibility
  • AAA Profile Integration: Manage authentication, authorization, and accounting profiles alongside user data
  • Organization Support: Associate users with specific organizations for multi-tenant scenarios
  • External System Integration: Link users to external systems using external_id and klass fields
  • User Lifecycle Management: Track user creation, login history, and set expiration dates
  • Filtering and Pagination: Efficiently retrieve user lists with advanced filtering options

Common Use Cases:

  • User onboarding and account provisioning
  • Integration with existing user directories (LDAP, Active Directory)
  • Multi-tenant application user management
  • Access control and permission management
  • User activity tracking and reporting

Endpoints

GET /user/

Description: Retrieves a paginated list of all users in the system, including their AAA profile information. This endpoint supports comprehensive filtering options to help you find specific users or groups of users based on various criteria.

Use Cases:

  • Display user directories or administration panels
  • Bulk user management operations
  • Integration with external systems requiring user synchronization
  • Reporting and analytics on user base

Full URL Example:

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

Parameters:

Parameter Type In Required Description
id string query No Filter by specific user ID
username string query No Filter by username (partial matches supported)
organization string query No Filter by organization ID
limit integer query No Number of results to return per page (default: 20)
offset integer query No Starting position for results (for pagination)

cURL Example:

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

Example Response:

{
  "count": 150,
  "next": "https://gate.zequenze.com/api/v1/user/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": 1,
      "username": "john.doe",
      "external_id": "AD_12345",
      "klass": "employee",
      "email": "john.doe@company.com",
      "first_name": "John",
      "last_name": "Doe",
      "is_active": true,
      "organization": 123,
      "description": "Senior Network Administrator",
      "date_joined": "2024-01-15T10:30:00Z",
      "first_login": "2024-01-15T14:22:00Z",
      "last_login": "2024-03-20T09:15:00Z",
      "expiration": "2025-01-15T00:00:00Z",
      "avatar_url": "https://avatars.company.com/john.doe.jpg",
      "source_id": 5,
      "profile": ["network_admin", "vpn_user", "reporting_viewer"]
    }
  ]
}

Response Codes:

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

POST /user/

Description: Creates a new user account in the system with associated AAA profiles. This endpoint allows you to provision new users with all necessary account information and access permissions in a single operation.

Use Cases:

  • User onboarding and account provisioning
  • Batch user creation from external systems
  • Self-service account creation workflows
  • Integration with HR systems for automatic account setup

Full URL Example:

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

Request Body Parameters:

Parameter Type Required Description
username string Yes Unique 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 account 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 short-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": "jane.smith",
    "password": "SecurePassword123!",
    "email": "jane.smith@company.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "external_id": "HR_67890",
    "klass": "contractor",
    "organization": 123,
    "description": "Network Security Specialist",
    "expiration": "2024-12-31T23:59:59Z",
    "profile": ["security_admin", "vpn_user"]
  }'

Example Response:

{
  "id": 25,
  "username": "jane.smith",
  "external_id": "HR_67890",
  "klass": "contractor",
  "email": "jane.smith@company.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "is_active": true,
  "organization": 123,
  "description": "Network Security Specialist",
  "date_joined": "2024-03-20T10:30:00Z",
  "first_login": null,
  "last_login": null,
  "expiration": "2024-12-31T23:59:59Z",
  "avatar_url": null,
  "profile": ["security_admin", "vpn_user"]
}

Response Codes:

Status Description
201 Created - User successfully created
400 Bad Request - Invalid data or validation errors
401 Unauthorized - Invalid or missing API token
409 Conflict - Username already exists

GET /user/username/{username}/

Description: Retrieves detailed information for a specific user by their username. This endpoint is particularly useful when you know the username but not the numeric ID, which is common in username-based authentication systems.

Use Cases:

  • User profile lookups during authentication
  • Username-based user management interfaces
  • Integration with systems that reference users by username
  • User self-service profile viewing

Full URL Example:

https://gate.zequenze.com/api/v1/user/username/john.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.doe/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 1,
  "username": "john.doe",
  "external_id": "AD_12345",
  "klass": "employee",
  "email": "john.doe@company.com",
  "first_name": "John",
  "last_name": "Doe",
  "is_active": true,
  "organization": 123,
  "description": "Senior Network Administrator",
  "date_joined": "2024-01-15T10:30:00Z",
  "first_login": "2024-01-15T14:22:00Z",
  "last_login": "2024-03-20T09:15:00Z",
  "expiration": "2025-01-15T00:00:00Z",
  "avatar_url": "https://avatars.company.com/john.doe.jpg",
  "source_id": 5,
  "profile": ["network_admin", "vpn_user", "reporting_viewer"]
}

Response Codes:

Status Description
200 Success - Returns user details
401 Unauthorized - Invalid or missing API token
404 Not Found - Username does not exist

PUT /user/username/{username}/

Description: Completely updates a user's information by username, replacing all fields with the provided data. This is a full update operation that requires all user fields to be specified in the request body.

Use Cases:

  • Complete user profile updates from external systems
  • Bulk user data synchronization
  • Administrative user account management
  • Migration between user management systems

Full URL Example:

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

cURL Example:

curl -X PUT "https://gate.zequenze.com/api/v1/user/username/john.doe/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe",
    "email": "j.doe@company.com",
    "first_name": "John",
    "last_name": "Doe",
    "external_id": "AD_12345_UPDATED",
    "klass": "senior_employee",
    "is_active": true,
    "organization": 123,
    "description": "Lead Network Administrator",
    "expiration": "2025-06-30T23:59:59Z",
    "profile": ["network_admin", "vpn_user", "reporting_admin", "security_viewer"]
  }'

Response Codes:

Status Description
200 Success - User updated successfully
400 Bad Request - Invalid data or validation errors
401 Unauthorized - Invalid or missing API token
404 Not Found - Username does not exist

PATCH /user/username/{username}/

Description: Partially updates a user's information by username, allowing you to modify only specific fields without affecting others. This is more efficient than PUT when you only need to change a few attributes.

Use Cases:

  • Updating specific user attributes (email, phone, department)
  • Status changes (activate/deactivate users)
  • Profile adjustments without full data reload
  • Incremental user data updates

Full URL Example:

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

cURL Example:

curl -X PATCH "https://gate.zequenze.com/api/v1/user/username/john.doe/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe.updated@company.com",
    "description": "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 data or validation errors
401 Unauthorized - Invalid or missing API token
404 Not Found - Username does not exist

DELETE /user/username/{username}/

Description: Permanently deletes a user account by username. This operation removes all user data and associated AAA profiles from the system and cannot be undone.

Use Cases:

  • Employee offboarding processes
  • Account cleanup and maintenance
  • Compliance with data retention policies
  • Removing test or temporary accounts

Full URL Example:

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

cURL Example:

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

Response Codes:

Status Description
204 No Content - User successfully deleted
401 Unauthorized - Invalid or missing API token
404 Not Found - Username does not exist

GET /user/{id}/

Description: Retrieves detailed information for a specific user by their numeric ID. This endpoint is ideal when you have the user's ID from previous API calls or database references.

Use Cases:

  • Retrieving user details with known ID from database
  • Following references from other API responses
  • Administrative interfaces using numeric identifiers
  • System-to-system integrations using ID-based references

Full URL Example:

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

cURL Example:

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

Response Codes:

Status Description
200 Success - Returns user details
401 Unauthorized - Invalid or missing API token
404 Not Found - User ID does not exist

PUT /user/{id}/

Description: Completely updates a user's information by ID, replacing all fields with the provided data. Similar to the username-based PUT endpoint but uses numeric ID for identification.

Full URL Example:

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

cURL Example:

curl -X PUT "https://gate.zequenze.com/api/v1/user/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe.updated",
    "email": "john.updated@company.com",
    "first_name": "John",
    "last_name": "Doe",
    "is_active": true,
    "organization": 123,
    "profile": ["network_admin", "security_admin"]
  }'

Response Codes:

Status Description
200 Success - User updated successfully
400 Bad Request - Invalid data or validation errors
401 Unauthorized - Invalid or missing API token
404 Not Found - User ID does not exist

PATCH /user/{id}/

Description: Partially updates a user's information by ID, allowing modification of specific fields only. This provides the same partial update functionality as the username-based PATCH endpoint.

Full URL Example:

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

cURL Example:

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

Response Codes:

Status Description
200 Success - User partially updated
400 Bad Request - Invalid data or validation errors
401 Unauthorized - Invalid or missing API token
404 Not Found - User ID does not exist

DELETE /user/{id}/

Description: Permanently deletes a user account by ID. This operation has the same effect as the username-based DELETE but uses numeric ID for identification.

Full URL Example:

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

cURL Example:

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

Response Codes:

Status Description
204 No Content - User successfully deleted
401 Unauthorized - Invalid or missing API token
404 Not Found - User ID does not exist

Common Use Cases

Use Case 1: Employee Onboarding Workflow

When a new employee joins, create their account with appropriate AAA profiles, set expiration based on contract length, and link to external HR systems using the external_id field.

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

Use Case 2: User Directory Synchronization

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

Endpoints Used: GET /user/, PATCH /user/{id}/, POST /user/

Use Case 3: Access Management and Compliance

Monitor user access by retrieving user profiles, updating AAA profiles based on role changes, and setting expiration dates for temporary access.

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

Use Case 4: Automated Account Lifecycle Management

Implement automated processes to deactivate expired accounts, remove inactive users, and generate compliance reports based on user data.

Endpoints Used: GET /user/, PATCH /user/{id}/, DELETE /user/{id}/

Use Case 5: Self-Service User Management

Allow users to view and update their own profile information through a web interface while restricting access to administrative fields.

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

Best Practices

  • Use Pagination Effectively: Always implement pagination when retrieving user lists to avoid performance issues with large user bases. Start with reasonable page sizes (20-50 users).

  • Implement Proper Error Handling: 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 username-based endpoints when integrating with username-centric systems, and ID-based endpoints for database-driven applications.

  • Secure Password Handling: Never log or store passwords in plaintext. The API handles password hashing automatically, but ensure secure transmission using HTTPS.

  • AAA Profile Management: Carefully manage AAA profiles as they directly impact user permissions. Implement approval workflows for profile changes in production environments.

  • Data Consistency: When using external_id for 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 retry logic for large-scale user management tasks.

Back to top