Service Token API

The Service Token API allows administrators to create, list, revoke, restore, and delete Service Tokens for Service Users 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.

Prerequisites

Service Tokens are tied to Service Users. Before creating a Service Token, you must first create a Service User through the Security settings or the Create Service User page.

---

List Service Tokens

Retrieve all Service Tokens across all Service Users.

Endpoint: GET /api/user-tokens/service

Permission: Admin user role

Example request and response

Request:

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

Response:

[
  {
    "id": 10,
    "created": "2026-01-15T10:30:00Z",
    "name": "Airflow Service User",
    "active": true,
    "expiration": "2027-01-15T10:30:00Z",
    "last_used": "2026-04-09T14:22:15Z",
    "user": {
      "id": 45,
      "user_id": "svc_airflow@service",
      "user_name": "svc_airflow",
      "email": "svc_airflow@service",
      "name": "Airflow Service User",
      "role": "Member",
      "user_type": "Service"
    }
  },
  {
    "id": 11,
    "created": "2026-03-01T08:00:00Z",
    "name": "dbt Cloud Integration",
    "active": false,
    "expiration": "2026-09-01T08:00:00Z",
    "last_used": "2026-04-07T09:15:00Z",
    "user": {
      "id": 46,
      "user_id": "svc_dbt@service",
      "user_name": "svc_dbt",
      "email": "svc_dbt@service",
      "name": "dbt Cloud Integration",
      "role": "Manager",
      "user_type": "Service"
    }
  }
]

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 Service Tokens List Columns page.

---

Create Service Token

Generate a new Service Token for a Service User.

Endpoint: POST /api/user-tokens

Permission: Admin 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 Service User.
user_id	integer	Yes	—	The ID of the Service User to create the token for. The target must be a Service User — attempting to assign a token to a regular user account returns an error.
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/*).

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 Service Token that expires in 1 year

Request:

curl -X POST "https://your-instance.qualytics.io/api/user-tokens" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Airflow Service User",
    "user_id": 45,
    "expires_in_days": 365
  }'

Response:

{
  "id": 10,
  "created": "2026-04-09T10:30:00Z",
  "name": "Airflow Service User",
  "active": true,
  "expiration": "2027-04-09T10:30:00Z",
  "last_used": null,
  "user": {
    "id": 45,
    "user_id": "svc_airflow@service",
    "user_name": "svc_airflow",
    "email": "svc_airflow@service",
    "name": "Airflow Service User",
    "role": "Member",
    "user_type": "Service"
  },
  "bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Create a SCIM-only Service Token

Request:

curl -X POST "https://your-instance.qualytics.io/api/user-tokens" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Directory Sync Token",
    "user_id": 47,
    "expires_in_days": 365,
    "scim_endpoints_only": true
  }'

Response:

{
  "id": 12,
  "created": "2026-04-09T10:35:00Z",
  "name": "Directory Sync Token",
  "active": true,
  "expiration": "2027-04-09T10:35:00Z",
  "last_used": null,
  "user": {
    "id": 47,
    "user_id": "directory_sync@service",
    "user_name": "directory_sync",
    "email": "directory_sync@service",
    "name": "Directory Sync",
    "role": "Admin",
    "user_type": "Service"
  },
  "bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Warning

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

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

---

Revoke Service Token

Deactivate a Service 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: Admin user role

Request Body:

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

Revoke a Service Token

Request:

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

Response:

{
  "id": 10,
  "created": "2026-04-09T10:30:00Z",
  "name": "Airflow Service User",
  "active": false,
  "expiration": "2027-04-09T10:30:00Z",
  "last_used": "2026-04-09T14:22:15Z",
  "user": {
    "id": 45,
    "user_id": "svc_airflow@service",
    "user_name": "svc_airflow",
    "email": "svc_airflow@service",
    "name": "Airflow Service User",
    "role": "Member",
    "user_type": "Service"
  }
}

Warning

Revoking a Service Token is immediate. Any automated system using this token will immediately lose API access.

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

---

Restore Service Token

Reactivate a previously revoked Service Token.

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

Permission: Admin user role

Request Body:

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

Restore a revoked Service Token

Request:

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

Response:

{
  "id": 10,
  "created": "2026-04-09T10:30:00Z",
  "name": "Airflow Service User",
  "active": true,
  "expiration": "2027-04-09T10:30:00Z",
  "last_used": "2026-04-09T14:22:15Z",
  "user": {
    "id": 45,
    "user_id": "svc_airflow@service",
    "user_name": "svc_airflow",
    "email": "svc_airflow@service",
    "name": "Airflow Service User",
    "role": "Member",
    "user_type": "Service"
  }
}

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 Service Token page.

---

Delete Service Token

Permanently remove a revoked Service Token. This action cannot be undone.

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

Permission: Admin user role

Delete a revoked Service Token

Request:

curl -X DELETE "https://your-instance.qualytics.io/api/user-tokens/10" \
  -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 Service Token page.

---

Using the Token

Once you have a bearer_token, include it in the Authorization header of all API requests. The request authenticates as the Service User with its assigned role and team permissions.

Example: Trigger a scan operation using a Service Token

curl -X POST "https://your-instance.qualytics.io/api/datastores/42/scan" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "container_names": ["orders", "customers"]
  }'

Example: Python usage with a Service Token

import requests

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

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

# List datastores accessible to the Service User
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, target user is not a Service User, or invalid request.
401 Unauthorized	Missing or invalid API token.
403 Forbidden	User does not have the Admin role.
404 Not Found	Token or Service User with the specified ID does not exist.
409 Conflict	Token name already exists for this Service User.
422 Unprocessable Entity	Invalid field values (e.g., expires_in_days outside 1–365 range).

Note

Error messages may refer to "service users" — this is the API term for Service Users.

Error response examples

403 Forbidden (non-admin attempting to create a Service Token):

{ "detail": "Only admins can manage tokens for service users" }

400 Bad Request (target user is not a Service User):

{ "detail": "Token management via this endpoint is restricted to service users" }

409 Conflict (duplicate token name):

{ "detail": "Token 'Airflow Service User' already exists for user svc_airflow" }

400 Bad Request (deleting an active token):

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

---

Permission Summary

Operation	Minimum Permission
List all Service Tokens	Admin user role
Create Service Token	Admin user role
Create SCIM-only Service Token	Admin user role
Revoke / restore Service Token	Admin user role
Delete Service Token	Admin user role

Info

Service Token API endpoints require the Admin role for all operations. To manage your own Personal Tokens, see the Personal Token API page.