Skip to main content

User

Manage user accounts and AAA (Authentication, Authorization, and Accounting) profile information.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Endpoints

GET /user/

Retrieve a list of users with optional filtering by ID, username, or organization.

Parameters:

Parameter Type In Required Description
id string query No Filter by user ID
username string query No Filter by username
organization string query No Filter by organization
limit integer query No Number of results to return per page
offset integer query No The initial index from which to return the results

Example Request:

GET /api/v1/user/?organization=acme&limit=20&offset=0

Example Response:

{
  "count": 45,
  "next": "https://gate.zequenze.com/api/v1/user/?limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": "12345",
      "username": "john.doe",
      "email": "john.doe@acme.com",
      "organization": "acme",
      "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "role": "admin",
        "created_at": "2024-01-15T10:30:00Z"
      }
    }
  ]
}
Status Description
200 Success
401 Unauthorized

POST /user/

Create a new user account with AAA profile information.

Parameters:

Parameter Type In Required Description
data object body Yes User data object

Example Request:

POST /api/v1/user/
Content-Type: application/json

{
  "username": "jane.smith",
  "email": "jane.smith@acme.com",
  "password": "secure_password123",
  "organization": "acme",
  "profile": {
    "first_name": "Jane",
    "last_name": "Smith",
    "role": "user"
  }
}

Example Response:

{
  "id": "67890",
  "username": "jane.smith",
  "email": "jane.smith@acme.com",
  "organization": "acme",
  "profile": {
    "first_name": "Jane",
    "last_name": "Smith",
    "role": "user",
    "created_at": "2024-01-20T14:22:00Z"
  }
}
Status Description
201 Created
400 Bad Request
401 Unauthorized

GET /user/username/{username}/

Retrieve a specific user by their username.

Example Request:

GET /api/v1/user/username/john.doe/

Example Response:

{
  "id": "12345",
  "username": "john.doe",
  "email": "john.doe@acme.com",
  "organization": "acme",
  "profile": {
    "first_name": "John",
    "last_name": "Doe",
    "role": "admin",
    "created_at": "2024-01-15T10:30:00Z",
    "last_login": "2024-01-20T09:15:00Z"
  }
}
Status Description
200 Success
404 User not found
401 Unauthorized

PUT /user/username/{username}/

Update a user's complete information by username.

Parameters:

Parameter Type In Required Description
data object body Yes Complete user data object

Example Request:

PUT /api/v1/user/username/john.doe/
Content-Type: application/json

{
  "username": "john.doe",
  "email": "john.doe@newcompany.com",
  "organization": "newcompany",
  "profile": {
    "first_name": "John",
    "last_name": "Doe",
    "role": "manager"
  }
}

Example Response:

{
  "id": "12345",
  "username": "john.doe",
  "email": "john.doe@newcompany.com",
  "organization": "newcompany",
  "profile": {
    "first_name": "John",
    "last_name": "Doe",
    "role": "manager",
    "updated_at": "2024-01-20T16:45:00Z"
  }
}
Status Description
200 Success
404 User not found
401 Unauthorized

PATCH /user/username/{username}/

Partially update a user's information by username.

Parameters:

Parameter Type In Required Description
data object body Yes Partial user data object

Example Request:

PATCH /api/v1/user/username/john.doe/
Content-Type: application/json

{
  "profile": {
    "role": "senior_admin"
  }
}

Example Response:

{
  "id": "12345",
  "username": "john.doe",
  "email": "john.doe@acme.com",
  "organization": "acme",
  "profile": {
    "first_name": "John",
    "last_name": "Doe",
    "role": "senior_admin",
    "updated_at": "2024-01-20T17:30:00Z"
  }
}
Status Description
200 Success
404 User not found
401 Unauthorized

DELETE /user/username/{username}/

Delete a user by their username.

Example Request:

DELETE /api/v1/user/username/john.doe/
Status Description
204 No Content (Success)
404 User not found
401 Unauthorized

GET /user/{id}/

Retrieve a specific user by their ID.

Example Request:

GET /api/v1/user/12345/

Example Response:

{
  "id": "12345",
  "username": "john.doe",
  "email": "john.doe@acme.com",
  "organization": "acme",
  "profile": {
    "first_name": "John",
    "last_name": "Doe",
    "role": "admin",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
Status Description
200 Success
404 User not found
401 Unauthorized

PUT /user/{id}/

Update a user's complete information by ID.

Parameters:

Parameter Type In Required Description
data object body Yes Complete user data object

Example Request:

PUT /api/v1/user/12345/
Content-Type: application/json

{
  "username": "john.doe.updated",
  "email": "john.doe.updated@acme.com",
  "organization": "acme",
  "profile": {
    "first_name": "John",
    "last_name": "Doe-Smith",
    "role": "super_admin"
  }
}
Status Description
200 Success
404 User not found
401 Unauthorized

PATCH /user/{id}/

Partially update a user's information by ID.

Parameters:

Parameter Type In Required Description
data object body Yes Partial user data object

Example Request:

PATCH /api/v1/user/12345/
Content-Type: application/json

{
  "email": "new.email@acme.com"
}
Status Description
200 Success
404 User not found
401 Unauthorized

DELETE /user/{id}/

Delete a user by their ID.

Example Request:

DELETE /api/v1/user/12345/
Status Description
204 No Content (Success)
404 User not found
401 Unauthorized

Best Practices

  • Pagination: Use limit and offset parameters for large datasets. Default page sizes are typically 20-100 items
  • Filtering: Combine query parameters for precise filtering (e.g., ?organization=acme&role=admin)
  • Error Handling: Always check status codes and handle 404 errors when accessing users by ID or username
  • Security: Never include passwords in response data. Use strong passwords when creating users
  • Performance: Use specific field queries when you only need partial user information
  • Validation: Ensure usernames are unique within organizations before creation
Back to top