# Personal Token API

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

---

## List Personal Tokens

Retrieve all Personal Access Tokens belonging to the current user.

**Endpoint**: `GET /api/user-tokens`

**Permission**: Member user role

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/user-tokens" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> [
>   {
>     "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": "user-123",
>       "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": "user-123",
>       "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](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/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. |

> **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 token that expires in 90 days**
>
> **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": "CI/CD Pipeline Token",
>     "expires_in_days": 90
>   }'
> ```
>
> **Response**:
>
> ```json
> {
>   "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": "user-123",
>     "user_name": "john.doe",
>     "email": "john.doe@example.com",
>     "name": "John Doe",
>     "role": "Member",
>     "user_type": "Human"
>   },
>   "bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
> }
> ```

> **Example: Create a token that never expires**
>
> **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": "Qualytics CLI",
>     "expires_in_days": null
>   }'
> ```
>
> **Response**:
>
> ```json
> {
>   "id": 2,
>   "created": "2026-04-09T10:35:00Z",
>   "name": "Qualytics CLI",
>   "active": true,
>   "expiration": null,
>   "last_used": null,
>   "user": {
>     "id": 42,
>     "user_id": "user-123",
>     "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](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/generate-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. |

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

> **Example: Restore a revoked token**
>
> **Request**:
>
> ```bash
> 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**:
>
> ```json
> {
>   "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": "user-123",
>     "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](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/restore-token/) page.

---

## Delete Personal Token

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

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

**Permission**: Member user role (own tokens only)

> **Example: Delete a revoked token**
>
> **Request**:
>
> ```bash
> 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** 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.

For the UI equivalent, see the [Delete Personal Token](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/delete-token/) page.

---

## Using the Token

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

> **Example: Example: List datastores using a Personal Token**
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/datastores" \
>   -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
> ```

> **Example: Example: Python usage**
>
> ```python
> 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())
> ```

## Timestamps

Every timestamp the API stores and returns is UTC, formatted as ISO 8601 with a trailing `Z` (for example, `2026-06-01T02:00:04.482Z`). The API does not convert to the timezone of the user or the deployment; if you need local time, convert on the client. Send timestamps in the same form, UTC with a trailing `Z`; values without a timezone are interpreted as UTC.

---

## Error Responses

| Status Code | Description |
| --- | --- |
| `400 Bad Request` | Active token that has not expired 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). |

> **Example: Error response examples**
>
> **409 Conflict** (duplicate token name):
>
> ```json
> { "detail": "Token 'CI/CD Pipeline Token' already exists for user john.doe" }
> ```
>
> **400 Bad Request** (deleting an active token that has not expired):
>
> ```json
> { "detail": "User Token id: 1 is active and can not be deleted. Revoke the token first" }
> ```
>
> **401 Unauthorized** (non-admin creating SCIM token):
>
> ```json
> { "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](https://userguide.qualytics.io/settings/access-tokens/service-token/api/) page.

*Last updated: November 13, 2026.*