# API tokens

URL: https://docs.vaultpanel.net/api-reference/api-tokens

> Create, list and revoke VaultPanel API tokens, and the scopes that decide which permissions a token carries on behalf of its owner.

API tokens let scripts, the [CLI](https://docs.vaultpanel.net/cli) and the [SDK](https://docs.vaultpanel.net/developers/sdk) call the API without a browser session. A token belongs to the person who created it and always acts as them. What it may do is the **overlap of its scopes and its owner's permissions**, so a token never does more than its owner, and narrowing the owner's role narrows their tokens at once.

Send it as a bearer token:

```http
Authorization: Bearer vpt_3J9cX0r…
```

## How tokens work

- **Format.** `vpt_` followed by 43 URL-safe characters. Only the token's SHA-256 is stored; the token itself is shown once, when it is created.
- **Owner.** Everyone manages their own tokens. People with `users.manage` can also list and revoke everyone's.
- **Limits.** Up to 25 active tokens per person. A token can expire after 1 to 3650 days, or never (until it is revoked).
- **Revocation.** Revoking takes effect immediately. A token also stops working when its owner is deactivated or, for a hosting customer, suspended or removed. A revoked or expired token answers `401 UNAUTHENTICATED`.
- **Interactive actions.** A token cannot create or revoke tokens, sign in, change passwords or two-factor settings, or open the server terminal. Under `/auth` it may only call [`GET /auth/me`](https://docs.vaultpanel.net/api-reference/authentication#get-the-current-identity).
- **Audit.** Every call is audited as the owner, with the token named in the actor label (`ada@example.com (token: deploy script)`). The token's last use, address and use count are recorded.

## Scopes

Scopes are groups of permissions. Give a token only what its script needs, and combine scopes freely. The `manage`, `deploy` and `servers` scopes change things but grant few read permissions, so most scripts pair them with `read`.

| Scope | Label | What it allows | Permissions |
| --- | --- | --- | --- |
| `read` | Read | View servers, websites, DNS zones, email, apps, databases, containers, backups, cron jobs, alerts and jobs | `dashboard.view`, `servers.read`, `websites.read`, `dns.read`, `mail.read`, `applications.read`, `databases.read`, `containers.read`, `backups.read`, `cron.read`, `alerts.read`, `jobs.read`, `security.read`, `users.read`, `roles.read`, `customers.read` |
| `logs` | Logs | Read website, app, container and server logs | `websites.logs`, `applications.logs`, `containers.logs`, `servers.logs`, `audit.read` |
| `deploy` | Deploy | Deploy, roll back, start, stop and restart apps and containers, and run cron jobs now | `applications.deploy`, `containers.operate`, `cron.run`, `jobs.read`, `applications.read`, `containers.read` |
| `manage` | Manage hosting | Create, change and delete websites, DNS zones, email, apps, databases, containers, backups and cron jobs | `websites.manage`, `dns.manage`, `mail.manage`, `files.read`, `files.write`, `applications.manage`, `databases.manage`, `containers.manage`, `backups.create`, `backups.manage`, `cron.manage`, `webhooks.manage`, `alerts.manage`, `alerts.acknowledge`, `jobs.cancel` |
| `servers` | Servers | Run server operations: services, processes, security settings and reboots | `servers.manage`, `servers.services`, `servers.processes`, `servers.signal`, `servers.reboot`, `servers.bulk`, `security.manage` |
| `customers` | Customers | Create, change, suspend and remove hosting customers and plans | `customers.manage`, `plans.manage` |
| `full` | Everything | Everything the owner may do, including panel settings and users | Every permission except `servers.terminal` |

The terminal (`servers.terminal`) is never available to a token: it opens only from the panel in a browser.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/api-tokens` | [List tokens](https://docs.vaultpanel.net/api-reference/api-tokens#list-tokens) |
| GET | `/api/v1/api-tokens/scopes` | [List scopes](https://docs.vaultpanel.net/api-reference/api-tokens#list-scopes) |
| POST | `/api/v1/api-tokens` | [Create a token](https://docs.vaultpanel.net/api-reference/api-tokens#create-a-token) |
| POST | `/api/v1/api-tokens/:id/revoke` | [Revoke a token](https://docs.vaultpanel.net/api-reference/api-tokens#revoke-a-token) |

## List tokens

`GET /api/v1/api-tokens`

Your tokens, active ones first, newest first. Never includes the token itself. Any signed-in person may list their own; listing everyone's needs `users.manage`.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `all` | boolean | No | `true` lists every person's tokens. Needs `users.manage`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/api-tokens \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items, canSeeAll } = await panel.apiTokens.list();
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "9a7e2c1d-4f60-4b2e-8d1a-6c3b5e7f9a20",
        "name": "deploy script",
        "prefix": "vpt_3J9cX0r",
        "scopes": ["read", "deploy"],
        "user": { "id": "3c9f0a52-7d1e-4b8a-9f3e-2a6d5c4b1e07", "email": "ada@example.com", "name": "Ada Lovelace" },
        "expiresAt": "2027-11-10T09:30:00.000Z",
        "expired": false,
        "lastUsedAt": "2026-11-10T11:05:12.000Z",
        "lastUsedIp": "198.51.100.24",
        "useCount": 418,
        "revokedAt": null,
        "createdAt": "2026-11-10T09:30:00.000Z"
      }
    ],
    "canSeeAll": true
  },
  "message": "OK",
  "requestId": "…"
}
```

`prefix` is the first 12 characters of the token, to recognize it. `canSeeAll` says whether you may use `all=true`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | `all=true` without `users.manage`. |

## List scopes

`GET /api/v1/api-tokens/scopes`

The scopes this panel offers. Tools installed separately (such as the CLI from npm) use it to describe the panel they talk to. `permissions` is the number of permissions in each scope.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/api-tokens/scopes \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.apiTokens.scopes();
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      { "key": "read", "label": "Read", "description": "View servers, websites, DNS zones, email, apps, databases, containers, backups, cron jobs, alerts and jobs", "permissions": 16 },
      { "key": "logs", "label": "Logs", "description": "Read website, app, container and server logs", "permissions": 5 }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## Create a token

`POST /api/v1/api-tokens` — Auth: session

Creates a token for the signed-in person. This is the only time the token is returned: store it in your secret manager. It can only be called from a browser session, which is what **Users & Access > API Tokens** in the panel does.

Scopes that cover permissions the owner does not have are kept on the token but grant nothing. A token whose scopes cover none of the owner's permissions is refused.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | 1 to 100 characters, to recognize the token later. |
| `scopes` | string[] | Yes | At least one of `read`, `logs`, `deploy`, `manage`, `servers`, `customers`, `full`. |
| `expiresInDays` | integer or null | No | 1 to 3650. Left out or `null`, the token does not expire. |

**Example request**

```bash
curl https://panel.example.com/api/v1/api-tokens -b cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"deploy script","scopes":["read","deploy"],"expiresInDays":365}'
```

**Response** `201 Created`

```json
{
  "success": true,
  "data": {
    "apiToken": { "id": "9a7e2c1d-4f60-4b2e-8d1a-6c3b5e7f9a20", "name": "deploy script", "prefix": "vpt_3J9cX0r", "scopes": ["read", "deploy"], "expiresAt": "2027-11-10T09:30:00.000Z", "lastUsedAt": null, "useCount": 0, "revokedAt": null, "createdAt": "2026-11-10T09:30:00.000Z" },
    "token": "vpt_3J9cX0rQ…"
  },
  "message": "API token created. Copy it now: it is not shown again.",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | Called with an API token, or the scopes cover none of your permissions. |
| 409 | `TOO_MANY_TOKENS` | You already have 25 active tokens. |
| 422 | `VALIDATION_ERROR` | No scopes, an unknown scope, or `expiresInDays` out of range. |

## Revoke a token

`POST /api/v1/api-tokens/:id/revoke` — Auth: session

Revokes a token immediately. You can revoke your own tokens; revoking someone else's needs `users.manage`. Revoking a revoked token changes nothing. Like creating, this is done from a browser session.

**Example request**

```bash
curl -X POST https://panel.example.com/api/v1/api-tokens/9a7e2c1d-4f60-4b2e-8d1a-6c3b5e7f9a20/revoke \
  -b cookies.txt -H "X-CSRF-Token: $CSRF_TOKEN"
```

**Response** `200 OK` with the token, now with `revokedAt` set.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | Called with an API token, or the token is someone else's and you lack `users.manage`. |
| 404 | `NOT_FOUND` | No such token. |
