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.

Last updated

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.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.
  • 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.

ScopeLabelWhat it allowsPermissions
readReadView servers, websites, DNS zones, email, apps, databases, containers, backups, cron jobs, alerts and jobsdashboard.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
logsLogsRead website, app, container and server logswebsites.logs, applications.logs, containers.logs, servers.logs, audit.read
deployDeployDeploy, roll back, start, stop and restart apps and containers, and run cron jobs nowapplications.deploy, containers.operate, cron.run, jobs.read, applications.read, containers.read
manageManage hostingCreate, change and delete websites, DNS zones, email, apps, databases, containers, backups and cron jobswebsites.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
serversServersRun server operations: services, processes, security settings and rebootsservers.manage, servers.services, servers.processes, servers.signal, servers.reboot, servers.bulk, security.manage
customersCustomersCreate, change, suspend and remove hosting customers and planscustomers.manage, plans.manage
fullEverythingEverything the owner may do, including panel settings and usersEvery permission except servers.terminal

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

Endpoints

MethodPathDescription
GET/api/v1/api-tokensList tokens
GET/api/v1/api-tokens/scopesList scopes
POST/api/v1/api-tokensCreate a token
POST/api/v1/api-tokens/:id/revokeRevoke a token

List tokens

GET/api/v1/api-tokens
Auth
Session cookie (+ CSRF token) or API token

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

NameTypeRequiredDescription
allbooleanNotrue 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

StatusCodeWhen
403FORBIDDENall=true without users.manage.

List scopes

GET/api/v1/api-tokens/scopes
Auth
Session cookie (+ CSRF token) or API token

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 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

POST/api/v1/api-tokens
Auth
Session cookie only (API tokens are refused)

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

FieldTypeRequiredDescription
namestringYes1 to 100 characters, to recognize the token later.
scopesstring[]YesAt least one of read, logs, deploy, manage, servers, customers, full.
expiresInDaysinteger or nullNo1 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

StatusCodeWhen
403FORBIDDENCalled with an API token, or the scopes cover none of your permissions.
409TOO_MANY_TOKENSYou already have 25 active tokens.
422VALIDATION_ERRORNo scopes, an unknown scope, or expiresInDays out of range.

Revoke a token

POST/api/v1/api-tokens/:id/revoke
Auth
Session cookie only (API tokens are refused)

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

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

StatusCodeWhen
403FORBIDDENCalled with an API token, or the token is someone else's and you lack users.manage.
404NOT_FOUNDNo such token.