Personal Token API

The Personal Token API allows you to create, list, revoke, restore, and delete your own Personal Access Tokens programmatically.

Tip

For complete API documentation, including request/response schemas, visit the API docs.

All endpoints are served from your Qualytics deployment (e.g., https://your-instance.qualytics.io). The paths below include the /api prefix.

List Personal Tokens

Retrieve all Personal Access Tokens belonging to the current user.

Endpoint: GET /api/user-tokens

Permission: Member user role

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/user-tokens" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

[
  {
    "id": 1,
    "created": "2026-01-15T10:30:00Z",
    "name": "CI/CD Pipeline Token",
    "active": true,
    "expiration": "2026-04-15T10:30:00Z",
    "last_used": "2026-04-09T14:22:15Z",
    "user": {
      "id": 42,
      "user_id": "auth0|abc123",
      "user_name": "john.doe",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "role": "Member",
      "user_type": "Human"
    }
  },
  {
    "id": 2,
    "created": "2026-03-01T08:00:00Z",
    "name": "Qualytics CLI",
    "active": false,
    "expiration": null,
    "last_used": null,
    "user": {
      "id": 42,
      "user_id": "auth0|abc123",
      "user_name": "john.doe",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "role": "Member",
      "user_type": "Human"
    }
  }
]

Note

The bearer_token field is not returned when listing tokens. The token value is only shown once at creation time.

For the UI equivalent, see the Personal Tokens List Columns page.

Create Personal Token

Generate a new Personal Access Token for the current user.

Endpoint: POST /api/user-tokens

Permission: Member user role

Request Body:

Field	Type	Required	Default	Description
`name`	`string`	Yes	—	A descriptive label for the token (max 255 characters). Must be unique per user.
`expires_in_days`	`integer` or `null`	No	`null`	Number of days until the token expires (1–365). Use `null` for no expiration.
`scim_endpoints_only`	`boolean`	No	`false`	Restrict the token to SCIM endpoints only (`/scim/v2/*`). Requires Admin role.

API vs UI expiration

The API accepts any integer from 1 to 365 for expires_in_days, giving you fine-grained control (e.g., 7 days, 45 days, 180 days). The UI only offers preset options: 30, 60, 90, 365 days, or Never.

Create a token that expires in 90 days

Request:

curl -X POST "https://your-instance.qualytics.io/api/user-tokens" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Token",
    "expires_in_days": 90
  }'

Response:

{
  "id": 1,
  "created": "2026-04-09T10:30:00Z",
  "name": "CI/CD Pipeline Token",
  "active": true,
  "expiration": "2026-07-08T10:30:00Z",
  "last_used": null,
  "user": {
    "id": 42,
    "user_id": "auth0|abc123",
    "user_name": "john.doe",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "role": "Member",
    "user_type": "Human"
  },
  "bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Create a token that never expires

Request:

curl -X POST "https://your-instance.qualytics.io/api/user-tokens" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Qualytics CLI",
    "expires_in_days": null
  }'

Response:

{
  "id": 2,
  "created": "2026-04-09T10:35:00Z",
  "name": "Qualytics CLI",
  "active": true,
  "expiration": null,
  "last_used": null,
  "user": {
    "id": 42,
    "user_id": "auth0|abc123",
    "user_name": "john.doe",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "role": "Member",
    "user_type": "Human"
  },
  "bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Warning

The bearer_token is returned only once at creation time. Store it immediately in a secure location (password manager, secrets vault, or environment variable). It cannot be retrieved later.

For the UI equivalent, see the Generate Personal Token page.

Revoke Personal Token

Deactivate a token to immediately prevent it from being used for API authentication.

Note

Revoke and restore share the same endpoint (PUT /api/user-tokens/{id}), differing only in the revoke value (true to revoke, false to restore).

Endpoint: PUT /api/user-tokens/{id}

Permission: Member user role (own tokens only)

Request Body:

Field	Type	Required	Description
`revoke`	`boolean`	Yes	Set to `true` to revoke the token.

Revoke a token

Request:

curl -X PUT "https://your-instance.qualytics.io/api/user-tokens/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "revoke": true
  }'

Response:

{
  "id": 1,
  "created": "2026-04-09T10:30:00Z",
  "name": "CI/CD Pipeline Token",
  "active": false,
  "expiration": "2026-07-08T10:30:00Z",
  "last_used": "2026-04-09T14:22:15Z",
  "user": {
    "id": 42,
    "user_id": "auth0|abc123",
    "user_name": "john.doe",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "role": "Member",
    "user_type": "Human"
  }
}

For the UI equivalent, see the Revoke Personal Token page.

Restore Personal Token

Reactivate a previously revoked token.

Endpoint: PUT /api/user-tokens/{id}

Permission: Member user role (own tokens only)

Request Body:

Field	Type	Required	Description
`revoke`	`boolean`	Yes	Set to `false` to restore the token.

Restore a revoked token

Request:

curl -X PUT "https://your-instance.qualytics.io/api/user-tokens/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "revoke": false
  }'

Response:

{
  "id": 1,
  "created": "2026-04-09T10:30:00Z",
  "name": "CI/CD Pipeline Token",
  "active": true,
  "expiration": "2026-07-08T10:30:00Z",
  "last_used": "2026-04-09T14:22:15Z",
  "user": {
    "id": 42,
    "user_id": "auth0|abc123",
    "user_name": "john.doe",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "role": "Member",
    "user_type": "Human"
  }
}

Note

The UI hides the Restore option for expired tokens. While the API technically allows setting {"revoke": false} on an expired token, this does not extend the expiration date — the token remains expired and will not work for authentication. Generate a new token instead.

For the UI equivalent, see the Restore Personal Token page.

Delete Personal Token

Permanently remove a revoked token. This action cannot be undone.

Endpoint: DELETE /api/user-tokens/{id}

Permission: Member user role (own tokens only)

Delete a revoked token

Request:

curl -X DELETE "https://your-instance.qualytics.io/api/user-tokens/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content (empty body)

Note

Only revoked tokens can be deleted. Attempting to delete an active token returns an error. Revoke the token first, then delete it.

For the UI equivalent, see the Delete Personal Token page.

Using the Token

Once you have a bearer_token, include it in the Authorization header of all API requests:

Example: List datastores using a Personal Token

curl -X GET "https://your-instance.qualytics.io/api/datastores" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example: Python usage

import requests

QUALYTICS_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
QUALYTICS_API = "https://your-instance.qualytics.io/api"

headers = {
    "Authorization": f"Bearer {QUALYTICS_TOKEN}",
    "Content-Type": "application/json"
}

response = requests.get(f"{QUALYTICS_API}/datastores", headers=headers)
print(response.json())

Error Responses

Status Code	Description
`400 Bad Request`	Active token cannot be deleted (revoke first), or invalid request.
`401 Unauthorized`	Missing or invalid API token, or non-admin attempting to create a SCIM-only token.
`403 Forbidden`	User does not have the required role.
`404 Not Found`	Token with the specified ID does not exist.
`409 Conflict`	Token name already exists for this user.
`422 Unprocessable Entity`	Invalid field values (e.g., `expires_in_days` outside 1–365 range).

Error response examples

409 Conflict (duplicate token name):

{ "detail": "Token 'CI/CD Pipeline Token' already exists for user john.doe" }

400 Bad Request (deleting an active token):

{ "detail": "User Token id: 1 is active and can not be deleted. Revoke the token first" }

401 Unauthorized (non-admin creating SCIM token):

{ "detail": "Only administrators can create tokens for scim endpoint management" }

Permission Summary

Operation	Minimum Permission
List personal tokens	Member user role
Create personal token	Member user role
Create SCIM-only token	Admin user role
Revoke / restore own token	Member user role
Delete own token	Member user role

Info

Personal Token API endpoints manage only the current user's tokens. To manage Service Tokens for automation, see the Service Token API page.