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 and the 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:
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.managecan 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
/authit may only callGET /auth/me. - 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 |
| GET | /api/v1/api-tokens/scopes | List scopes |
| POST | /api/v1/api-tokens | Create a token |
| POST | /api/v1/api-tokens/:id/revoke | Revoke a token |
List tokens
/api/v1/api-tokensYour 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 https://panel.example.com/api/v1/api-tokens \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items, canSeeAll } = await panel.apiTokens.list();Response 200 OK
{
"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
/api/v1/api-tokens/scopesThe 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 https://panel.example.com/api/v1/api-tokens/scopes \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.apiTokens.scopes();Response 200 OK
{
"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
/api/v1/api-tokensCreates 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
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
{
"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
/api/v1/api-tokens/:id/revokeRevokes 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
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. |
Authentication
How callers authenticate to the VaultPanel API, and the /auth endpoints for setup, sign-in, two-factor codes, sessions and password resets.
Users and roles
API reference for panel users (invite, update, deactivate, reset links and two-factor resets), the built-in roles and the audit log.