# Personal access tokens

Who a token acts as, and retiring the token you are using. A token can never make another token. 5 routes, from the API’s own OpenAPI document.

URL: https://docs.qaldy.com/reference/api/tokens/

5 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/).

## Routes

| Method | Path | What it does |
|---|---|---|
| [[GET]] | [`/​v1/​tokens/​self`](#get-v1-tokens-self) | Who the presented token acts as: workspace, person, role and scopes (tokens only) |
| [[DELETE]] | [`/​v1/​tokens/​self`](#delete-v1-tokens-self) | Revoke the token you present, at once (tokens only; `qaldy logout`) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​tokens`](#get-v1-workspaces-ws-tokens) | Your personal access tokens in this workspace (prefixes only) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​tokens`](#post-v1-workspaces-ws-tokens) | Create a personal access token; its value is in this answer only |
| [[DELETE]] | [`/​v1/​workspaces/​{ws}/​tokens/​{tokenId}`](#delete-v1-workspaces-ws-tokens-tokenid) | Revoke one of your tokens at once |

## Reference

### [[GET]] `/v1/tokens/self`

Who the presented token acts as: workspace, person, role and scopes (tokens only).

- **Authentication:** the console’s session cookie.
- **Token:** a personal access token or an MCP sign-in with the `read` scope.
- **Who:** a personal access token (any scope)

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `token` | object | yes |  |
| `token.id` | string | yes | at least 1 characters |
| `token.name` | string | yes | 1 to 60 characters |
| `token.scopes` | "read" · "write" · "admin"[] | yes | up to 3 items |
| `token.prefix` | string | yes | at least 1 characters |
| `token.last4` | string | yes | 4 to 4 characters |
| `token.createdAt` | string (date-time) | yes |  |
| `token.lastUsedAt` | string (date-time) or null | yes |  |
| `token.expiresAt` | string (date-time) or null | yes |  |
| `token.revokedAt` | string (date-time) or null | yes |  |
| `workspace` | object | yes |  |
| `workspace.id` | string | yes | at least 1 characters |
| `workspace.name` | string | yes | at least 1 characters |
| `workspace.slug` | string | yes | at least 1 characters |
| `user` | object | yes |  |
| `user.id` | string | yes | at least 1 characters |
| `user.name` | string | yes | at least 1 characters |
| `user.email` | string | yes | at least 3 characters |
| `role` | "owner" · "admin" · "builder" · "member" · "viewer" | yes |  |
| `oauth` | object |  |  |
| `oauth.grantId` | string | yes | at least 1 characters |
| `oauth.clientName` | string | yes | at least 1 characters |
| `oauth.clientKind` | "registered" · "metadata" | yes |  |
| `oauth.audience` | string | yes | at least 1 characters |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/tokens/self`

Revoke the token you present, at once (tokens only; `qaldy logout`).

- **Authentication:** the console’s session cookie.
- **Token:** a personal access token or an MCP sign-in with the `read` scope.
- **Who:** a personal access token (any scope)

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `ok` | true | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/tokens`

Your personal access tokens in this workspace (prefixes only).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | at least 1 characters |
| `name` | string | yes | 1 to 60 characters |
| `scopes` | "read" · "write" · "admin"[] | yes | up to 3 items |
| `prefix` | string | yes | at least 1 characters |
| `last4` | string | yes | 4 to 4 characters |
| `createdAt` | string (date-time) | yes |  |
| `lastUsedAt` | string (date-time) or null | yes |  |
| `expiresAt` | string (date-time) or null | yes |  |
| `revokedAt` | string (date-time) or null | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/workspaces/{ws}/tokens`

Create a personal access token; its value is in this answer only.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | 1 to 60 characters |
| `scopes` | "read" · "write" · "admin"[] | yes | up to 3 items |
| `expiresInDays` | integer or null |  | 1 to 365. default 90 |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `token` | object | yes |  |
| `token.id` | string | yes | at least 1 characters |
| `token.name` | string | yes | 1 to 60 characters |
| `token.scopes` | "read" · "write" · "admin"[] | yes | up to 3 items |
| `token.prefix` | string | yes | at least 1 characters |
| `token.last4` | string | yes | 4 to 4 characters |
| `token.createdAt` | string (date-time) | yes |  |
| `token.lastUsedAt` | string (date-time) or null | yes |  |
| `token.expiresAt` | string (date-time) or null | yes |  |
| `token.revokedAt` | string (date-time) or null | yes |  |
| `secret` | string | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/workspaces/{ws}/tokens/{tokenId}`

Revoke one of your tokens at once.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `tokenId` | path | string | yes | 1 to 64 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `ok` | true | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).