---
title: "API tokens"
description: "Manage personal API tokens from a signed-in session. Create, rotate and duplicate keys, change scopes with approval, and inspect token history and errors."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# API tokens

**Endpoint**: `/api/auth/tokens/`

Manage your personal API tokens. A personal token acts as you, within its scopes and your current roles. Token management shows only your own tokens. For automation that runs commands or transfers files, use a [service token](/reference/api/service-tokens/).

## Authentication

Token management and token history require a signed-in session, through the web console or the CLI after `alpacon login`. Personal API tokens and service tokens receive `403 permission_denied` on those routes. The scope and preset catalogs require authentication but do not require a signed-in session. All examples below use a signed-in session.

Use [`alpacon token`](/reference/cli/token/) to manage tokens from the CLI, or follow the [console steps](/use/settings/api-tokens/). The examples below require alpacon-cli 1.14.2 or later. Sign in to your workspace with `alpacon login`, then run [`alpacon api`](/reference/cli/api/) with your signed-in session. It prints the response body and prompts for MFA when needed.

Creating, duplicating and rotating personal tokens require a paid plan. Otherwise, the API returns `402 workspace_plan_update_required`.

  

## List API tokens

```http
GET /api/auth/tokens/
```

### Query parameters

| Parameter | Type | Description |
|---|---|---|
| `name` | string | Exact token name |
| `enabled` | boolean | Enabled status |
| `search` | string | Search by name |
| `ordering` | string | `added_at`, `updated_at`, `last_used_at`; prefix `-` for descending. Default `-updated_at` |
| `page` | integer | Page number |
| `page_size` | integer | Results per page (default 15, maximum 100) |

### Response

```json
{
  "count": 1,
  "current": 1,
  "next": null,
  "previous": null,
  "last": 1,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Inventory sync",
      "enabled": true,
      "scopes": [
        "server:read",
        "metric:read"
      ],
      "unreachable_scopes": [],
      "added_at": "2026-10-20T09:00:00Z",
      "updated_at": "2026-10-20T09:00:00Z",
      "expires_at": "2026-12-31T23:59:59Z",
      "last_used_at": null,
      "usage_count": 0
    }
  ]
}
```

Page links are integer page numbers. `unreachable_scopes` lists claimed scopes your current roles do not allow. Other scopes continue to work.

### Example

```bash
alpacon api -X GET "/api/auth/tokens/?enabled=true"
```

  
  

## Create API token

```http
POST /api/auth/tokens/
```

### Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Unique among your tokens; maximum 128 characters |
| `enabled` | boolean | No | Enable immediately |
| `scopes` | array | No | Scope list. Omit both this field and `presets` to derive scopes from your global roles |
| `presets` | array | No | Keys from the preset catalog; expanded and merged with explicit scopes |
| `expires_at` | datetime | No | Future expiry within the workspace maximum. Omitted or `null` sets the maximum lifetime from now |

The workspace maximum lifetime is 1–366 days, with a default of 366 days. Lowering that maximum does not shorten existing tokens.

Personal tokens never receive `*`, including tokens created by Superusers. Omitting `scopes` and `presets` derives concrete scopes from your global roles, excluding scopes personal tokens cannot carry. If that produces no scopes, creation fails with `api_token_scopes_required`. Explicit `scopes: []` without presets creates a token with no scopes.

An explicit `*` is refused with `api_token_scope_not_mintable`. Personal tokens also cannot be issued execution scopes: `command:create`, `command:purpose`, `downloaded_file:bulk`, `downloaded_file:create`, `downloaded_file:download`, `uploaded_file:bulk`, `uploaded_file:bulk_upload`, `uploaded_file:create` or `uploaded_file:upload`. Patterns covering any of those names, such as `command:*` or `*:create`, are refused with the same code. Interactive scopes and `server:register` or `cluster:register` cannot be issued either. See [Scopes](/reference/scopes/).

Every requested scope must fit your global role permissions. A wildcard such as `*:read` requires your role to hold that wildcard; only Superusers hold wildcard permissions. Presets exclude unavailable extension scopes and scopes personal tokens cannot carry, but still must fit your permissions at creation.

### Response

`201 Created` returns the list fields plus `key`, which starts with `alpat-`. Store the key when returned; it cannot be retrieved later.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Inventory sync",
  "enabled": true,
  "scopes": [
    "server:read",
    "metric:read"
  ],
  "unreachable_scopes": [],
  "added_at": "2026-10-20T09:00:00Z",
  "updated_at": "2026-10-20T09:00:00Z",
  "expires_at": "2026-12-31T23:59:59Z",
  "last_used_at": null,
  "usage_count": 0,
  "key": "alpat-xxxxxxxxxxxxxxxxxx"
}
```

### Example

```bash
alpacon api -X POST \
  -f 'name=Inventory sync' \
  -f 'scopes[]=server:read' \
  -f 'scopes[]=metric:read' \
  "/api/auth/tokens/"
```

  
  

## Get API token

```http
GET /api/auth/tokens/{token_id}/
```

`token_id` is one of your token UUIDs. The `200 OK` response includes the list fields plus:

| Field | Description |
|---|---|
| `effective_scopes` | Scopes usable under your current roles |
| `scope_usage` | Scopes used by the token |
| `pending_scope_expansion` | `null`, or an object with `id`, `requested_scopes`, `added_scopes`, `added_at` |

```bash
alpacon api -X GET "/api/auth/tokens/550e8400-e29b-41d4-a716-446655440000/"
```

  
  

## Update API token

```http
PATCH /api/auth/tokens/{token_id}/
PUT /api/auth/tokens/{token_id}/
```

### Request body

| Field | Type | Description |
|---|---|---|
| `name` | string | New unique name, up to 128 characters |
| `enabled` | boolean | Enable or disable the token |
| `scopes` | array | Full replacement list, checked against your roles and issuance restrictions |
| `expires_at` | datetime | Future expiry within the maximum; `null` resets it to the maximum lifetime from now |

Do not send `presets` on update. If a token has no expiry, editing it assigns one using the workspace maximum. Leaving an existing expiry unchanged does not require it to fit a newly lowered maximum.

### Response

`200 OK` returns the token for immediate changes. Replacing a scope within the token’s existing coverage or narrowing scopes is immediate. If the new list grants access outside that coverage, the response is `202 Accepted`. The token keeps its existing scopes until approval, while other fields in the same request apply immediately.

```json
{
  "status": "pending_approval",
  "approval_request_id": "0b7c2e5a-3f41-4d8e-9a6b-2c1d0e9f8a7b",
  "requested_scopes": [
    "server:read",
    "metric:read",
    "alert:read"
  ],
  "added_scopes": [
    "alert:read"
  ]
}
```

Each token can have only one pending scope expansion request. See `pending_scope_expansion` in [Get API token](#get-api-token). Approval rechecks the token owner’s permissions.

```bash
alpacon api -X PATCH \
  -F enabled=false \
  "/api/auth/tokens/550e8400-e29b-41d4-a716-446655440000/"
```

  
  

## Delete API token

```http
DELETE /api/auth/tokens/{token_id}/
```

Permanently deletes the token, closes Websh and WebFTP connections opened with it, and withdraws pending scope expansion. The response is `204 No Content`.

```bash
alpacon api -X DELETE "/api/auth/tokens/550e8400-e29b-41d4-a716-446655440000/"
```

  

## Rotate API token

```http
POST /api/auth/tokens/{token_id}/rotate/
```

Replace the key on the same token. No request fields are needed. The old key stops authenticating immediately, and connections opened with it close. Update the stored secret as part of the same operation. `usage_count` resets to `0` and `last_used_at` to `null`.

Scopes stay unchanged and are not checked again for issuance. An existing expiry stays unchanged; a token without one receives the workspace maximum lifetime from now. An expired token cannot be rotated.

`200 OK` returns the token with its new `key`, using the same fields as creation.

```bash
alpacon api -X POST "/api/auth/tokens/550e8400-e29b-41d4-a716-446655440000/rotate/"
```

## Duplicate API token

```http
POST /api/auth/tokens/{token_id}/duplicate/
```

Create a separate token while leaving the source key valid. The optional `name` is at most 128 characters. When omitted, the name is based on the source name with `(copy)` or a numbered copy suffix.

The copy keeps `enabled` and stored scopes except scopes personal tokens cannot be issued. If filtering removes every scope from a nonempty list, duplication fails with `api_token_scopes_required`. The copied expiry is limited to the workspace maximum. Server and file ACLs are copied; command ACLs are copied where command ACL writes are available. An expired source cannot be duplicated.

`201 Created` returns the new token and its one-time `key`, using the creation response fields.

```bash
alpacon api -X POST \
  -f 'name=Inventory sync backup' \
  "/api/auth/tokens/550e8400-e29b-41d4-a716-446655440000/duplicate/"
```

## Scope and preset catalogs

```http
GET /api/auth/tokens/scopes/
GET /api/auth/tokens/presets/
```

Both return `200 OK` without pagination. The scope response contains `resources` entries with `name`, `actions` and `acl`, limited to scopes your roles allow and the workspace offers for personal tokens. `wildcards` is an empty array, including for Superusers.

The preset response is an object keyed by preset ID. Each entry has `name` and `description` objects with `en` and `ko`, plus a `permissions` array. It filters out unavailable extensions and scopes personal tokens cannot carry. It does not filter by your roles; creation still checks your permission ceiling.

```bash
alpacon api -X GET "/api/auth/tokens/scopes/"
```

```bash
alpacon api -X GET "/api/auth/tokens/presets/"
```

## Token history

```http
GET /api/auth/token-history/
GET /api/auth/token-history/{history_id}/
```

Read changes to a token’s effective scopes after its owner’s roles change. Members see their own token history; admins see the workspace history. History remains readable after token deletion, with `api_token: null` and the saved `api_token_name`.

### Query parameters

| Parameter | Description |
|---|---|
| `api_token` | Existing token ID; for a deleted token, filter by name or owner instead |
| `api_token_name`, `token_user` | Exact token name or owner ID |
| `change_type`, `change_type__in` | Exact change type or comma-separated types |
| `added_at__gte`, `added_at__lte` | Time bounds |
| `ordering` | `added_at` or `-added_at` (default) |
| `page`, `page_size` | Integer pagination; default 15 entries, maximum 100 |

List responses use `count`, `current`, `next`, `previous`, `last`, `results`. Each result, or the detail response, contains `id`, `api_token`, `api_token_name`, `token_user`, `change_type`, `changes` and `added_at`. A scope reduction is recorded in `changes.effective_scopes.lost`.

```bash
alpacon api -X GET "/api/auth/token-history/?api_token_name=Inventory%20sync"
```

## Error responses

| Status | Error code | Description |
|---|---|---|
| 400 | `api_token_exists` | A token already has this name |
| 400 | `api_token_scope_invalid` | Malformed or unknown scope |
| 400 | `api_token_scope_exceeds_rbac` | Scope exceeds your global role permissions |
| 400 | `api_token_scope_not_mintable` | Scope or covering wildcard cannot be issued on a personal token |
| 400 | `api_token_scopes_required` | Default, preset or duplicate processing produced no usable scopes |
| 400 | `api_token_invalid_preset` | Unknown preset or its extension is off |
| 400 | `api_token_presets_not_allowed_on_update` | Use `scopes`, not `presets`, on update |
| 400 | `api_token_invalid_expiration` | Expiry is in the past |
| 400 | `api_token_expires_exceeds_max_ttl` | Expiry exceeds the workspace maximum lifetime |
| 400 | `api_token_already_expired` | Expired tokens cannot be revived, widened, duplicated or rotated |
| 400 | `api_token_scope_expansion_pending` | A scope expansion already awaits approval |
| 401 | `auth_token_missing` | Not authenticated, or credential is invalid or expired |
| 402 | `workspace_plan_update_required` | Create, duplicate and rotate require a paid plan |
| 403 | `permission_denied` | Management or history requested with a personal or service token |
| 403 | `workspace_suspended` | Writes refused while the workspace is suspended |
| 404 | `api_not_found` | Token or history entry is not accessible or does not exist |

Source: https://docs.alpacax.com/reference/api/tokens/
