User

Endpoints Summary

Method Path Swagger GET /user/ Swagger ↗ POST /user/ Swagger ↗ GET /user/username/{username}/ Swagger ↗ PUT /user/username/{username}/ Swagger ↗ PATCH /user/username/{username}/ Swagger ↗ DELETE /user/username/{username}/ Swagger ↗ GET /user/{id}/ Swagger ↗ PUT /user/{id}/ Swagger ↗ PATCH /user/{id}/ Swagger ↗ DELETE /user/{id}/ Swagger ↗

---

The User API providesendpoints provide comprehensive user management capabilities forincluding theauthentication, GATEauthorization, system,and allowingaccess control (AAA) profile management. These endpoints allow you to create, retrieve, update, and delete users alongin withyour system, manage their AAA (Authentication, Authorization, Accounting) profile information. These endpoints support both ID-basedprofiles and username-basedpermissions, operations,and makinghandle ituser flexiblelifecycle foroperations differentlike integrationaccount scenarios.expiration and status management.

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 and their associated AAA (Authentication, Authorization, and Accounting) profiles within the GATE system. ItThis API provides full CRUD (Create, Read, Update, Delete) operations for user management, withallowing additionalyou supportto for AAA profiles that defineintegrate user permissionsprovisioning, profile management, and access levels.control into your applications.

Key Features:

• DualUser AccessLifecycle MethodsManagement: AccessCreate, usersread, byupdate, eitherand numericdelete IDuser oraccounts usernamewith forcomprehensive maximumprofile flexibilityinformation
• AAA Profile Integration: Manage authentication, authorization,Assign and accountingmanage Authentication, Authorization, and Accounting profiles alongsidefor fine-grained access control

Flexible User Identification: Support for both internal ID-based operations and username-based operations for easier integration External System Integration: Built-in support for external IDs and service class references to link users with external systems Account Management: Handle user dataexpiration dates, activation status, and login tracking 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 optionsenvironments

Common UseIntegration Cases:Scenarios:

• Identity Provider Integration: Sync users from LDAP, Active Directory, or other identity systems

Application User Management: Provision users for web applications, network services, or cloud resources Automated Onboarding: Create user accounts as part of employee onboarding workflows Access Control Management: Assign and modify user permissions through AAA profile assignments User Analytics: Track user login patterns and account provisioninglifecycle for reporting and compliance Integration

The API supports both paginated listing of users with existingflexible filtering options and individual user directoriesoperations, (LDAP,making Activeit Directory)suitable

Multi-tenantfor applicationboth bulk operations and real-time user management Access control and permission management User activity tracking and reporting tasks.

---

Endpoints

GET /user/

Description: Retrieves a paginated list of all users in the system, including their AAA profile assignments and comprehensive user information. This endpoint supports comprehensiveflexible filtering optionsby touser helpID, you find specific usersusername, or groupsorganization, ofmaking usersit basedideal onfor varioususer criteria.search functionality, bulk operations, and administrative dashboards.

Use Cases:

• DisplayBuilding user directoriesmanagement orinterfaces administrationwith panelssearch and filtering capabilities

Synchronizing user data between systems Generating user reports and analytics Bulk user management operations Integration with external systems requiring user synchronization Reporting and analytics on user baseauditing

Full URL Example:

https://gate.zequenze.com/api/v1/user/?username=john.doe&organization=123&is_active=true1&limit=2050&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 matches supported)matching)
organization	string	query	No	Filter users by organization ID
limit	integer	query	No	Number of results to return per page (default: 20)20, max: 100)
offset	integer	query	No	StartingThe positioninitial index from which to return the results for results (for pagination)pagination

cURL Example:

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

Example Response:

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

Response Codes:

Status	Description
200	Success - Returns paginated userlist listof users
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to viewlist users

---

POST /user/

Description: Creates a new user account in the system with associatedoptional AAA profiles.profile assignments. This endpoint allows you to provision new users with allcomprehensive necessaryprofile accountinformation, informationexternal system references, and initial access permissionspermissions. inThe ausername singleis operation.the only required field, with all other user attributes being optional.

Use Cases:

• User onboarding and account provisioning workflows
• BatchAutomated user creation from externalHR systems or identity providers
• Self-service account creationregistration workflowsprocesses
• IntegrationBulk withuser HRimport systems for automatic account setupoperations

Full URL Example:

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

Request Body Parameters:Schema:

ParameterField	Type	Required	Description
username	string	Yes	Unique username (150 chars max, alphanumericletters, anddigits, @/./+/-/:/|/_ only)
password	string	No	User password (will be hashed automatically)hashed)
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 referenceidentifier
is_active	boolean	No	Whether user account isAccount active status (default: true)
organization	integer	No	Organization ID to associate user with
description	string	No	Additional user description or notes
expiration	string	No	UserAccount expiration date (ISO 8601 format)
avatar_url	string	No	URL to user's avatar image
profile	array	No	ArrayList of AAA profile short-names to assign

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",
    "password": "SecurePassword123!",
    "external_id": "HR_67890",
    "klass": "contractor"EMP005678",
    "organization": 123,1,
    "description": "NetworkSoftware Security Specialist"Developer",
    "expiration": "2024-2025-12-31T23:59:59Z",
    "profile": ["security_admin"developer_access", "vpn_user"]
  }'

Example Response:

{
  "id": 25,42,
  "username": "jane.smith",
  "external_id": "HR_67890"EMP005678",
  "klass": "contractor",null,
  "email": "jane.smith@company.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "is_active": true,
  "organization": 123,1,
  "description": "NetworkSoftware Security Specialist"Developer",
  "date_joined": "2024-03-20T10:21T10:30:00Z",
  "first_login": null,
  "last_login": null,
  "expiration": "2024-2025-12-31T23:59:59Z",
  "avatar_url": null,
  "profile": ["security_admin"developer_access", "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 identified by their username. This endpoint is particularly useful when you know the username but not the numericinternal user ID, whichmaking isit commonideal infor username-baseduser authenticationlookup systems.operations and profile management interfaces.

Use Cases:

• User profile lookups duringin authenticationapplications
• Username-based userauthentication managementflows

User information display in administrative interfaces Integration with systems that referenceuse usersusernames byas usernameprimary User self-service profile viewingidentifiers

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"EMP001234",
  "klass": "employee"standard_employee",
  "email": "john.doe@company.com",
  "first_name": "John",
  "last_name": "Doe",
  "is_active": true,
  "organization": 123,1,
  "description": "Senior Network Administrator"Engineer",
  "date_joined": "2024-01-15T10:30:00Z",
  "first_login": "2024-01-15T14:22:16T08:15:00Z",
  "last_login": "2024-03-20T09:15:20T14:22:00Z",
  "expiration": "2025-01-15T00:00:00Z"15T23:59:59Z",
  "avatar_url": "https://avatars.company.gate.zequenze.com/avatars/john.doe.jpg",
  "source_id": 5,1,
  "profile": ["network_admin", "vpn_user", "reporting_viewer"wifi_access"]
}

Response Codes:

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

---

PUT /user/username/{username}/

Description: Completely updatesreplaces aall user'suser information by username, replacing all fields withfor the providedspecified data.username. This isendpoint performs a full updateupdate, operation that requiresrequiring all user fields to be specifiedprovided inas it will overwrite the requestexisting body.user record entirely. Use PATCH for partial updates instead.

Use Cases:

• Complete user profile updatessynchronization from external systems
• BulkUser usermigration between systems with full data synchronizationreplacement
• Administrative user account management

Migration betweenbulk user managementupdates systemswhere all fields are known

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.john.doe@newcompany.com",
    "first_name": "John",
    "last_name": "Doe"Doe-Smith",
    "external_id": "AD_12345_UPDATED"EMP001234",
    "klass": "senior_employee",
    "is_active": true,
    "organization": 123,2,
    "description": "LeadPrincipal Network Administrator"Architect",
    "expiration": "2025-06-30T23:2026-01-15T23:59:59Z",
    "profile": ["network_admin", "vpn_user"infrastructure_admin", "reporting_admin", "security_viewer"vpn_user"]
  }'

Response Codes:

Status	Description
200	Success - User successfully 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 updatesPerforms a user'spartial update of user information byfor username,the allowingspecified youusername. toOnly modify only specificthe fields withoutprovided affectingin others.the request body will be updated, leaving all other user attributes unchanged. This is morethe efficientpreferred thanmethod PUTfor whenmaking youspecific only needchanges to changeuser a few attributes.accounts.

Use Cases:

• Updating specific user attributes (email,like phone,email department)or organization
• StatusModifying changesAAA (activate/deactivateprofile users)assignments
• ProfileActivating adjustmentsor withoutdeactivating fulluser data reloadaccounts
• IncrementalExtending or modifying user dataexpiration updatesdates

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.doe@updated-email.com",
    "description"organization": "Senior Network Administrator - Updated Role",3,
    "profile": ["network_admin", "vpn_user", "reporting_viewer", "audit_viewer"new_access_profile"]
  }'

Response Codes:

Status	Description
200	Success - User partiallysuccessfully 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 athe user account identified by the specified username. This operation removescannot be undone and will remove all user datadata, including AAA profile assignments and associatedhistorical AAAlogin profiles from the system and cannot be undone.information.

Use Cases:

• EmployeeUser offboarding processes

and Accountaccount cleanup and maintenance Compliance with data retention policies Removing test accounts or temporaryinvalid accountsuser records Compliance-driven account deletion requirements Automated account lifecycle management

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 identified by their numericinternal user ID. This endpoint is ideal when you haveprovides the user'same functionality as the username-based lookup but uses the system's internal ID fromas previousthe API calls or database references.identifier.

Use Cases:

• Retrieving user detailsinformation withwhen knownyou have the internal ID from database
• Following references from other API responses that include user IDs
• AdministrativeBuilding interfacesrelationships usingbetween numericusers identifiers

and System-to-other system integrations using ID-based referencesentities

Full URL Example:

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

cURL Example:

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

Response Codes:

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

---

PUT /user/{id}/

Description: Completely updatesreplaces all user information for the specified user ID. This endpoint performs a user'sfull informationupdate, by ID, replacingrequiring all fields withto be provided as it will overwrite the providedexisting data.user Similarrecord to the username-based PUT endpoint but uses numeric ID for identification.entirely.

Full URL Example:

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

cURL Example:

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

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

---

DELETEPATCH /user/{id}/

Description: Permanently deletesPerforms a partial update of user accountinformation byfor the specified user ID. This operation hasOnly the samefields effectprovided asin the username-basedrequest DELETEbody butwill usesbe numericupdated, IDmaking this ideal for identification.targeted modifications to user accounts.

Full URL Example:

https://gate.zequenze.com/api/v1/user/123/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,
    "description": "Account suspended pending review"
  }'

Response Codes:

Status Description 200 Success - User successfully 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 the user account identified by the specified user ID. This operation cannot be undone and will remove all user data and associated relationships.

Full URL Example:

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

cURL Example:

curl -X DELETE "https://gate.zequenze.com/api/v1/user/123/42/" \
  -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,joins your organization, you can automate their account creation and access provisioning using POST /user/ to create theirthe account with appropriate AAA profiles, setthen expirationuse basedPATCH on contract length, and linkoperations to externalupdate HRtheir systemsinformation usingas thethey external_idprogress field.

through

Endpointsonboarding Used: POST /user/, PATCH /user/username/{username}/stages.

Use Case 2: User Directory Synchronization

RegularlyFor syncorganizations users fromusing external directoriesidentity (LDAP/AD)providers, byuse listing all users, comparing with external data, and updating changed information using partial updates.

Endpoints Used: GET /user/, with filtering to retrieve current users, compare with your external directory, then use POST to create new users and PATCH /user/{id}/,to POSTupdate /user/existing ones, ensuring your GATE system stays synchronized.

Use Case 3: Access Management and Compliance

MonitorUse GET /user/ to generate reports on user access byand retrievingexpiration dates, then use PATCH operations to update user profiles, updating AAA profiles based on role changes, and settingmodify expiration datesdates, foror temporarydeactivate access.

accounts

Endpointsthat Used:no GETlonger /user/username/{username}/,require PATCHaccess, /user/{id}/maintaining compliance with security policies.

Use Case 4: AutomatedSelf-Service Profile Management

Build user portals where users can view their information using GET /user/username/{username}/ and submit profile updates that your system processes using PATCH /user/username/{username}/ after appropriate approval workflows.

Use Case 5: Account Lifecycle ManagementAutomation

Implement automated processes that monitor user activity and account status, using PATCH operations to extend expiration dates for active users, deactivate expireddormant accounts, removeor inactiveDELETE users,accounts andthat generateare complianceno reportslonger needed based on useryour data.

organization's

Endpointsretention 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}/policies.

---

Best Practices

• Use Pagination Effectively: AlwaysWhen listing users, always implement proper pagination whenusing retrievinglimit userand listsoffset parameters to avoid performance issues with large user bases.datasets. Start with reasonable page sizes (20-25-50 users). and adjust based on your application's needs.

Leverage Username-Based Operations: For user-facing applications, prefer the username-based endpoints (/user/username/{username}/) as they're more intuitive and don't expose internal system IDs. Reserve ID-based operations for internal system integrations.

Implement Proper Error Handling: CheckAlways check response codes and handle common errorsscenarios like 404 (user not found) and, 409 (username conflicts), and 401 (authentication failures) gracefully in your applications.

ChooseManage AAA Profiles Carefully: When updating user profiles, retrieve the Rightcurrent Endpoint:profile Uselist username-basedfirst endpointsto whenavoid integratingaccidentally withremoving username-centricnecessary 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 useraccess permissions. ImplementConsider implementing approval workflows for profile changes inthat productiongrant environments.additional access.

DataUse ConsistencyPartial Updates: WhenPrefer usingPATCH external_idover forPUT system integration, ensure these IDs remain consistent across all systemsoperations to maintainavoid properaccidentally clearing user linking.data. PATCH operations are safer and more efficient as they only modify the specified fields.

MonitoringMonitor andAccount AuditingExpiration: Implement loggingmonitoring for all user managementexpiration operations, especially creationdates and deletion,automate toextension maintainor securitynotification auditprocesses. trails.Users with expired accounts may lose access unexpectedly if not properly managed.

RateSecure LimitingSensitive Operations: BeImplement mindfuladditional ofvalidation APIand rateapproval limitsprocesses for sensitive operations like user deletion or profile modifications that grant administrative access.

Cache User Information Wisely: Consider caching user information for frequently accessed data, but ensure cache invalidation strategies are in place for when performinguser bulkinformation operations.changes, Implementespecially appropriatefor delaysauthentication and retryauthorization logic for large-scale user management tasks.data.

---