API Reference

Authentication

How callers authenticate to the VaultPanel API, and the /auth endpoints for setup, sign-in, two-factor codes, sessions and password resets.

Last updated

The API accepts several kinds of credentials, one per kind of caller. Scripts send an API token. The panel's own interface uses a session cookie, which is what the /auth endpoints on this page create and manage.

Credentials

CredentialHeaderUsed byDetails
API tokenAuthorization: Bearer vpt_…Scripts, the CLI, the SDKActs as its owner, narrowed to its scopes. No CSRF token needed. See API tokens.
Session cookieCookie: vp_session=… and X-CSRF-TokenThe panel in a browserCreated by sign-in. HttpOnly, SameSite=Strict, and Secure on HTTPS.
Plugin tokenAuthorization: Bearer vpp_…PluginsWhat the owner approved for the plugin. See Plugins.
Billing API keyvpk_…Billing systemsOnly on /billing. See Billing.
Agent signatureSigned headersServer agentsOnly on /agent. See Agent.
Webhook tokenIn the URLGit hostsOnly on /hooks/deploy/:token. See Git push hooks.

When a request carries an API token, the token wins and any session cookie is ignored.

API tokens and /auth

Signing in and out, passwords, two-factor settings and sessions stay interactive. An API token may call GET /auth/me and nothing else under /auth. The other signed-in endpoints on this page answer 403 FORBIDDEN to a token.

Sessions and CSRF

A browser session lasts 12 hours by default (VAULTPANEL_SESSION_TTL_HOURS). Every state-changing request made with the session cookie (anything but GET, HEAD and OPTIONS) must send the session's CSRF token in the X-CSRF-Token header. Sign-in and GET /auth/me return it as csrfToken. A missing or wrong token answers 403 FORBIDDEN.

Requests made with an API token carry no cookie, so they need no CSRF token.

Two-factor policy

An owner or admin can require two-factor sign-in for some roles (see Sign-in and two-factor). A covered account without it can still sign in, but every endpoint outside /auth answers 403 TWO_FACTOR_SETUP_REQUIRED until it turns two-factor sign-in on. Sign-in responses say so in twoFactorSetupRequired.

Address restrictions

When the panel only accepts approved addresses, requests from other addresses answer 403 IP_NOT_ALLOWED, including sign-in. See Panel access.

Endpoints

MethodPathDescription
GET/api/v1/auth/setupGet setup status
POST/api/v1/auth/setupCreate the owner account
POST/api/v1/auth/loginSign in
POST/api/v1/auth/login/2faComplete two-factor sign-in
POST/api/v1/auth/ssoSign in with a billing link
GET/api/v1/auth/meGet the current identity
POST/api/v1/auth/logoutSign out
POST/api/v1/auth/passwordChange your password
POST/api/v1/auth/2fa/setupStart two-factor setup
POST/api/v1/auth/2fa/enableTurn on two-factor sign-in
POST/api/v1/auth/2fa/disableTurn off two-factor sign-in
POST/api/v1/auth/2fa/recovery-codesReplace recovery codes
GET/api/v1/auth/sessionsList your sessions
POST/api/v1/auth/sessions/sign-out-othersSign out other sessions
DELETE/api/v1/auth/sessions/:idSign out a session
POST/api/v1/auth/password-reset/requestRequest a password reset
POST/api/v1/auth/password-reset/inspectInspect a reset or invite link
POST/api/v1/auth/password-reset/completeSet a password from a link

The examples for session endpoints use a cURL cookie jar (-c saves the cookie, -b sends it) and fetch from a page served by the panel.

Get setup status

GET/api/v1/auth/setup
Auth
None

Whether the panel still needs its first owner, and whether the sign-in page can offer "Forgot password?" (true when panel email is set up).

Example request

curl https://panel.example.com/api/v1/auth/setup

Response 200 OK

{ "success": true, "data": { "needsSetup": false, "passwordResetByEmail": true }, "message": "OK", "requestId": "…" }

Create the owner account

POST/api/v1/auth/setup
Auth
None

Creates the first owner with the setup token the installer printed (sudo vaultpanel setup-token shows it again) and signs them in. Works once: after the first owner exists it answers 409.

Request body

FieldTypeRequiredDescription
setupTokenstringYesThe panel's setup token.
namestringYes1 to 120 characters.
emailstringYesA valid email address.
passwordstringYes12 to 256 characters.

Example request

curl https://panel.example.com/api/v1/auth/setup -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"setupToken":"15d59a807f148df64628dd4ca0abd16c","name":"Ada Lovelace","email":"ada@example.com","password":"correct-horse-battery"}'

Response 201 Created. Sets the vp_session cookie and returns the same data as Sign in.

Errors

StatusCodeWhen
403INVALID_SETUP_TOKENThe setup token is wrong.
409ALREADY_SET_UPThe panel already has an owner.
422VALIDATION_ERRORA field is invalid, such as a password under 12 characters.
429RATE_LIMITEDMore than 10 attempts in 15 minutes.

Sign in

POST/api/v1/auth/login
Auth
None

Checks an email and password. Without two-factor sign-in it starts a session, sets the vp_session cookie and returns the signed-in user. With two-factor sign-in on, it returns a challenge instead: send it with a code to Complete two-factor sign-in.

Request body

FieldTypeRequiredDescription
emailstringYesThe account's email address.
passwordstringYesThe account's password.

Example request

curl https://panel.example.com/api/v1/auth/login -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","password":"correct-horse-battery"}'
const res = await fetch('/api/v1/auth/login', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'ada@example.com', password: 'correct-horse-battery' }),
});
const { data } = await res.json();
const csrfToken = data.csrfToken; // send as X-CSRF-Token on later changes

Response 200 OK, signed in

{
  "success": true,
  "data": {
    "user": {
      "id": "3c9f0a52-7d1e-4b8a-9f3e-2a6d5c4b1e07",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "isActive": true,
      "twoFactorEnabled": false,
      "roles": ["owner"],
      "lastLoginAt": "2026-11-10T09:14:03.000Z",
      "createdAt": "2026-10-20T08:00:00.000Z",
      "updatedAt": "2026-11-10T09:14:03.000Z"
    },
    "permissions": ["dashboard.view", "users.read", "users.manage", "…"],
    "csrfToken": "…",
    "customer": null,
    "twoFactorSetupRequired": false
  },
  "message": "Signed in",
  "requestId": "…"
}

customer is set for a hosting customer's account and null for staff.

Response 200 OK, two-factor code needed

{ "success": true, "data": { "twoFactorRequired": true, "challengeToken": "…" }, "message": "Enter your two-factor code", "requestId": "…" }

Errors

StatusCodeWhen
401INVALID_CREDENTIALSThe email or password is wrong, or the account is deactivated.
403ACCOUNT_SUSPENDEDA hosting customer's account is suspended or closed (said only after the right password).
403IP_NOT_ALLOWEDThe panel does not accept sign-ins from this address.
429ACCOUNT_LOCKEDFive failed attempts in a row lock the account for 15 minutes.
429RATE_LIMITEDMore than 20 attempts from this address in 15 minutes.

Complete two-factor sign-in

POST/api/v1/auth/login/2fa
Auth
None

The second step of sign-in. Send the challenge from Sign in with either a 6-digit code from the authenticator app or one of the account's recovery codes. The challenge is valid for 5 minutes. Each recovery code works once.

Request body

FieldTypeRequiredDescription
challengeTokenstringYesFrom the sign-in response.
codestringOne of the twoThe current 6-digit code.
recoveryCodestringOne of the twoA recovery code such as abcde-12345.

Example request

curl https://panel.example.com/api/v1/auth/login/2fa -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"challengeToken":"…","code":"492817"}'

Response 200 OK. Sets the vp_session cookie and returns the same data as Sign in. After a recovery code it also returns recoveryCodesLeft.

Errors

StatusCodeWhen
401UNAUTHENTICATEDThe challenge expired. Sign in again.
401INVALID_CODEThe code is wrong, or the recovery code was already used.
403ACCOUNT_SUSPENDED, IP_NOT_ALLOWEDAs for Sign in.
422VALIDATION_ERRORNeither or both of code and recoveryCode were sent.
429ACCOUNT_LOCKEDToo many failed attempts.
POST/api/v1/auth/sso
Auth
None

Exchanges a one-time sign-in link made by a billing system (the panel opens it as /sso#token=…) for a session. A link is valid for 2 minutes and works once. See Billing.

Request body

FieldTypeRequiredDescription
tokenstringYesThe token from the link.

Response 200 OK. Sets the vp_session cookie and returns the same data as Sign in.

Errors

StatusCodeWhen
401LOGIN_LINK_INVALIDThe link expired, was already used, or its account is deactivated.

Get the current identity

GET/api/v1/auth/me
Auth
Session cookie (+ CSRF token) or API token

Who the session or token belongs to and what it may do. This is the only /auth endpoint an API token may call, which makes it the CLI's whoami.

Example request

curl https://panel.example.com/api/v1/auth/me \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const me = await panel.me();

Response 200 OK

{
  "success": true,
  "data": {
    "user": { "id": "3c9f0a52-7d1e-4b8a-9f3e-2a6d5c4b1e07", "email": "ada@example.com", "name": "Ada Lovelace", "isActive": true, "twoFactorEnabled": true, "roles": ["owner"], "lastLoginAt": "…", "createdAt": "…", "updatedAt": "…" },
    "permissions": ["dashboard.view", "servers.read", "websites.read", "…"],
    "customer": null,
    "csrfToken": null,
    "apiToken": { "id": "9a7e2c1d-…", "name": "deploy script", "scopes": ["read", "deploy"] },
    "twoFactorSetupRequired": false,
    "recoveryCodesLeft": 9
  },
  "message": "OK",
  "requestId": "…"
}
  • With a token, permissions are the overlap of the token's scopes and its owner's permissions, apiToken names the token and csrfToken is null.
  • With a session, csrfToken is the token to send as X-CSRF-Token and apiToken is null.
  • With a plugin token, user is null and plugin names the plugin and its scopes.
  • recoveryCodesLeft is null when two-factor sign-in is off.

Errors

StatusCodeWhen
401UNAUTHENTICATEDNo valid session or token.

Sign out

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

Ends the current session and clears the cookie.

Example request

curl -X POST https://panel.example.com/api/v1/auth/logout -b cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"

Response 200 OK with data: null and the message Signed out.

Change your password

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

Changes the signed-in person's password and signs out their other sessions.

Request body

FieldTypeRequiredDescription
currentPasswordstringYesThe password in use now.
newPasswordstringYes12 to 256 characters.

Example request

curl https://panel.example.com/api/v1/auth/password -b cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" -H "Content-Type: application/json" \
  -d '{"currentPassword":"correct-horse-battery","newPassword":"a-longer-passphrase-2026"}'

Response 200 OK with data: null.

Errors

StatusCodeWhen
422VALIDATION_ERRORcurrentPassword is incorrect, or newPassword is too short.

Start two-factor setup

POST/api/v1/auth/2fa/setup
Auth
Session cookie only (API tokens are refused)

Creates a new TOTP secret for the signed-in person. Show otpauthUrl as a QR code (or the secret as text) in an authenticator app, then confirm it with Turn on two-factor sign-in.

Response 200 OK

{ "success": true, "data": { "secret": "JBSWY3DPEHPK3PXP…", "otpauthUrl": "otpauth://totp/…" }, "message": "Scan the code, then confirm it", "requestId": "…" }

Errors

StatusCodeWhen
409TWO_FACTOR_ALREADY_ENABLEDTwo-factor sign-in is already on.

Turn on two-factor sign-in

POST/api/v1/auth/2fa/enable
Auth
Session cookie only (API tokens are refused)

Confirms the secret from setup with a current code, turns two-factor sign-in on and returns 10 recovery codes. They are shown once: keep them somewhere safe.

Request body

FieldTypeRequiredDescription
codestringYesThe current 6-digit code.

Response 200 OK

{ "success": true, "data": { "recoveryCodes": ["k7m2p-x9q4r", "…"] }, "message": "Two-factor sign-in is on. Save your recovery codes.", "requestId": "…" }

Errors

StatusCodeWhen
400BAD_REQUESTSetup was not started.
409TWO_FACTOR_ALREADY_ENABLEDTwo-factor sign-in is already on.
422VALIDATION_ERRORThe code is not valid.

Turn off two-factor sign-in

POST/api/v1/auth/2fa/disable
Auth
Session cookie only (API tokens are refused)

Turns two-factor sign-in off for the signed-in person and deletes their recovery codes. Needs the password and a current code.

Request body

FieldTypeRequiredDescription
passwordstringYesThe account's password.
codestringYesThe current 6-digit code.

Response 200 OK with data: null.

Errors

StatusCodeWhen
400BAD_REQUESTTwo-factor sign-in is not on.
422VALIDATION_ERRORThe password or code is incorrect (details names which).

Replace recovery codes

POST/api/v1/auth/2fa/recovery-codes
Auth
Session cookie only (API tokens are refused)

Makes 10 new recovery codes. The old ones stop working.

Request body

FieldTypeRequiredDescription
passwordstringYesThe account's password.
codestringYesThe current 6-digit code.

Response 200 OK with data.recoveryCodes, as for Turn on two-factor sign-in.

Errors

StatusCodeWhen
400BAD_REQUESTTwo-factor sign-in is not on.
422VALIDATION_ERRORThe password or code is incorrect.

List your sessions

GET/api/v1/auth/sessions
Auth
Session cookie only (API tokens are refused)

The signed-in person's active sessions, most recently used first (up to 200).

Response 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "5e2b8c71-…",
        "ip": "198.51.100.24",
        "userAgent": "Mozilla/5.0 …",
        "createdAt": "2026-11-10T09:14:03.000Z",
        "lastSeenAt": "2026-11-10T11:02:40.000Z",
        "expiresAt": "2026-11-10T21:14:03.000Z",
        "current": true
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}

Sign out other sessions

POST/api/v1/auth/sessions/sign-out-others
Auth
Session cookie only (API tokens are refused)

Ends every session of the signed-in person except the current one.

Response 200 OK

{ "success": true, "data": { "count": 2 }, "message": "Signed out 2 other sessions", "requestId": "…" }

Sign out a session

DELETE/api/v1/auth/sessions/:id
Auth
Session cookie only (API tokens are refused)

Ends one of the signed-in person's other sessions.

Response 200 OK with data: null.

Errors

StatusCodeWhen
400BAD_REQUESTIt is the current session. Use Sign out.
404NOT_FOUNDNo such active session of yours.

Request a password reset

POST/api/v1/auth/password-reset/request
Auth
None

The "Forgot password?" request. Answers the same way whether or not the address has an account, then emails a reset link when it has one. Each account gets at most one email every 5 minutes. Needs panel email.

Request body

FieldTypeRequiredDescription
emailstringYesThe account's email address.

Response 202 Accepted

{ "success": true, "data": null, "message": "If this address has an account, a reset link is on its way.", "requestId": "…" }

Errors

StatusCodeWhen
409EMAIL_OFFThe panel cannot send email. An administrator can issue a reset link instead.
429RATE_LIMITEDMore than 20 requests from this address in 15 minutes.
POST/api/v1/auth/password-reset/inspect
Auth
None

Says whose link a token is and what it is for, before the person chooses a password. Reset links are valid for 2 hours and invite links for 72 hours. The token is the part after #token= in the link.

Request body

FieldTypeRequiredDescription
tokenstringYesThe token from the link.

Response 200 OK

{ "success": true, "data": { "email": "grace@example.com", "name": "Grace Hopper", "purpose": "invite" }, "message": "OK", "requestId": "…" }

purpose is invite or reset.

Errors

StatusCodeWhen
400INVALID_RESET_TOKENThe link is invalid or has expired.
POST/api/v1/auth/password-reset/complete
Auth
None

Sets the account's password from an invite or reset link and signs out its existing sessions. The link stops working.

Request body

FieldTypeRequiredDescription
tokenstringYesThe token from the link.
passwordstringYes12 to 256 characters.

Response 200 OK

{ "success": true, "data": null, "message": "Password set. You can sign in now.", "requestId": "…" }

Errors

StatusCodeWhen
400INVALID_RESET_TOKENThe link is invalid, expired or already used.
422VALIDATION_ERRORThe password is too short.