# Service Token API

Source: https://userguide.qualytics.io/settings/access-tokens/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](https://userguide.qualytics.io/api/docs).

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

> **Info: Prerequisites**
>
> Service Tokens are tied to **Service Users**. Before creating a Service Token, you must first create a Service User through the [Access settings](https://userguide.qualytics.io/settings/access/service-users/introduction/) or the [Create Service User](https://userguide.qualytics.io/settings/access/service-users/managing/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: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/user-tokens/service" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> [
>   {
>     "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](https://userguide.qualytics.io/settings/access-tokens/service-token/managing/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/*`). |

> **Note: 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.

> **Example: Create a Service Token that expires in 1 year**
>
> **Request**:
>
> ```bash
> 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**:
>
> ```json
> {
>   "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..."
> }
> ```

> **Example: Create a SCIM-only Service Token**
>
> **Request**:
>
> ```bash
> 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**:
>
> ```json
> {
>   "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](https://userguide.qualytics.io/settings/access-tokens/service-token/managing/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. |

> **Example: Revoke a Service Token**
>
> **Request**:
>
> ```bash
> 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**:
>
> ```json
> {
>   "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](https://userguide.qualytics.io/settings/access-tokens/service-token/managing/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. |

> **Example: Restore a revoked Service Token**
>
> **Request**:
>
> ```bash
> 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**:
>
> ```json
> {
>   "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.

> **Note: Tokens of a deleted Service User**
>
> A token whose Service User has been deleted cannot be restored. The request returns `400 Bad Request` with `Unable to reactivate a token for a deleted user`. Revoking the token again (`{"revoke": true}`) still succeeds.

For the UI equivalent, see the [Restore Service Token](https://userguide.qualytics.io/settings/access-tokens/service-token/managing/restore-service-token/) page.

---

## Delete Service Token

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

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

**Permission**: Admin user role

> **Example: Delete a revoked Service Token**
>
> **Request**:
>
> ```bash
> 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** or **expired** tokens can be deleted. Attempting to delete an active token that has not expired returns an error. Revoke the token first, then delete it. An expired token can be deleted right away, without revoking it first.
>
> A revoked token can still be deleted after its Service User has been deleted, so you can clean up tokens left behind by a removed Service User.

For the UI equivalent, see the [Delete Service Token](https://userguide.qualytics.io/settings/access-tokens/service-token/managing/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: Example: Trigger a scan operation using a Service Token**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/operations/run" \
>   -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
>   -H "Content-Type: application/json" \
>   -d '{
>     "type": "scan",
>     "datastore_id": 42,
>     "container_names": ["orders", "customers"]
>   }'
> ```

> **Example: Example: Python usage with a Service Token**
>
> ```python
> 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 that has not expired cannot be deleted, a token of a deleted Service User cannot be restored, 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**.

> **Example: Error response examples**
>
> **403 Forbidden** (non-admin attempting to create a Service Token):
>
> ```json
> { "detail": "Only admins can manage tokens for service users" }
> ```
>
> **400 Bad Request** (target user is not a Service User):
>
> ```json
> { "detail": "Token management via this endpoint is restricted to service users" }
> ```
>
> **409 Conflict** (duplicate token name):
>
> ```json
> { "detail": "Token 'Airflow Service User' already exists for user svc_airflow" }
> ```
>
> **400 Bad Request** (deleting an active token that has not expired):
>
> ```json
> { "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](https://userguide.qualytics.io/settings/access-tokens/personal-token/api/) page.

*Last updated: November 13, 2026.*