> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickbase.so/llms.txt
> Use this file to discover all available pages before exploring further.

# API tokens

> Self-manage the current workspace's personal access tokens over the API — the twin of the Developers settings page.

Self-manage the current workspace's personal access tokens over the API — the twin of the **Developers** settings page. Tokens are scoped to the acting token's workspace, so you only ever see and manage tokens minted for that workspace.

All endpoints require `Authorization: Bearer {token}`. See [Authentication](/api/authentication) for how a token is bound to its workspace and how the optional site allowlist works.

### List tokens

```http theme={null}
GET /api/tokens
```

List the workspace's active (non-revoked) tokens, newest first.

**Response** — flat JSON array of:

| Field          | Type                      | Description                                                  |
| -------------- | ------------------------- | ------------------------------------------------------------ |
| `id`           | string                    | Token id (used to revoke it).                                |
| `name`         | string                    | The name given at creation.                                  |
| `site_ids`     | string\[] \| null         | Allowed site UUIDs. `null` means all sites in the workspace. |
| `last_used_at` | string (ISO 8601) \| null | When the token last authenticated a request.                 |
| `created_at`   | string (ISO 8601) \| null | When the token was created.                                  |

Status: `200 OK`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl https://clickbase.so/api/tokens \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  await fetch('https://clickbase.so/api/tokens', {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  })
  ```

  ```python title="Python" theme={null}
  requests.get('https://clickbase.so/api/tokens', headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'})
  ```
</CodeGroup>

### Create a token

```http theme={null}
POST /api/tokens
```

Mint a personal access token bound to the current workspace.

**Body parameters**

| Parameter  | Type              | Required | Description                                                                                                                             |
| ---------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `name`     | string            | Yes      | Label for the token. Max 255 chars.                                                                                                     |
| `site_ids` | string\[] \| null | No       | Site allowlist: an array of site UUIDs in this workspace. Omit, pass `null`, or pass `["*"]` for all sites. Foreign UUIDs return `422`. |

**Response** — the created token. Only this response includes the one-time plaintext `token` field, which is never persisted and can never be shown again. Status: `201 Created`.

| Field          | Type                      | Description                                           |
| -------------- | ------------------------- | ----------------------------------------------------- |
| `id`           | string                    | Token id.                                             |
| `name`         | string                    | Token name.                                           |
| `site_ids`     | string\[] \| null         | Allowed site UUIDs. `null` means all sites.           |
| `last_used_at` | string (ISO 8601) \| null | Always null on a fresh token.                         |
| `created_at`   | string (ISO 8601) \| null | When the token was created.                           |
| `token`        | string                    | The one-time plaintext bearer token. **Copy it now.** |

<CodeGroup>
  ```bash title="curl" theme={null}
  curl -X POST https://clickbase.so/api/tokens \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"name": "Reporting script"}'
  ```

  ```javascript title="JavaScript" theme={null}
  await fetch('https://clickbase.so/api/tokens', {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', Accept: 'application/json' },
    body: JSON.stringify({ name: 'Reporting script' }),
  })
  ```

  ```python title="Python" theme={null}
  requests.post(
      'https://clickbase.so/api/tokens',
      headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
      json={'name': 'Reporting script'},
  )
  ```
</CodeGroup>

```json theme={null}
{
    "id": "42",
    "name": "Reporting script",
    "site_ids": null,
    "last_used_at": null,
    "created_at": "2026-07-11T12:00:00.000000Z",
    "token": "eyJ0eXAiOiJKV1QiLCJ..."
}
```

### Revoke a token

```http theme={null}
DELETE /api/tokens/{token}
```

Revoke a token. Resolved through the workspace, so a foreign/unknown id returns `404`.

**Path parameters**

| Parameter | Type   | Required | Description                                      |
| --------- | ------ | -------- | ------------------------------------------------ |
| `token`   | string | Yes      | The token id (from the list or create response). |

Status: `204 No Content`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl -X DELETE https://clickbase.so/api/tokens/42 \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  await fetch('https://clickbase.so/api/tokens/42', {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  })
  ```

  ```python title="Python" theme={null}
  requests.delete('https://clickbase.so/api/tokens/42', headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'})
  ```
</CodeGroup>