Authentication
How callers authenticate to the VaultPanel API, and the /auth endpoints for setup, sign-in, two-factor codes, sessions and password resets.
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
| Credential | Header | Used by | Details |
|---|---|---|---|
| API token | Authorization: Bearer vpt_… | Scripts, the CLI, the SDK | Acts as its owner, narrowed to its scopes. No CSRF token needed. See API tokens. |
| Session cookie | Cookie: vp_session=… and X-CSRF-Token | The panel in a browser | Created by sign-in. HttpOnly, SameSite=Strict, and Secure on HTTPS. |
| Plugin token | Authorization: Bearer vpp_… | Plugins | What the owner approved for the plugin. See Plugins. |
| Billing API key | vpk_… | Billing systems | Only on /billing. See Billing. |
| Agent signature | Signed headers | Server agents | Only on /agent. See Agent. |
| Webhook token | In the URL | Git hosts | Only 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
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/auth/setup | Get setup status |
| POST | /api/v1/auth/setup | Create the owner account |
| POST | /api/v1/auth/login | Sign in |
| POST | /api/v1/auth/login/2fa | Complete two-factor sign-in |
| POST | /api/v1/auth/sso | Sign in with a billing link |
| GET | /api/v1/auth/me | Get the current identity |
| POST | /api/v1/auth/logout | Sign out |
| POST | /api/v1/auth/password | Change your password |
| POST | /api/v1/auth/2fa/setup | Start two-factor setup |
| POST | /api/v1/auth/2fa/enable | Turn on two-factor sign-in |
| POST | /api/v1/auth/2fa/disable | Turn off two-factor sign-in |
| POST | /api/v1/auth/2fa/recovery-codes | Replace recovery codes |
| GET | /api/v1/auth/sessions | List your sessions |
| POST | /api/v1/auth/sessions/sign-out-others | Sign out other sessions |
| DELETE | /api/v1/auth/sessions/:id | Sign out a session |
| POST | /api/v1/auth/password-reset/request | Request a password reset |
| POST | /api/v1/auth/password-reset/inspect | Inspect a reset or invite link |
| POST | /api/v1/auth/password-reset/complete | Set 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
/api/v1/auth/setupWhether 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/setupResponse 200 OK
{ "success": true, "data": { "needsSetup": false, "passwordResetByEmail": true }, "message": "OK", "requestId": "…" }Create the owner account
/api/v1/auth/setupCreates 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
| Field | Type | Required | Description |
|---|---|---|---|
setupToken | string | Yes | The panel's setup token. |
name | string | Yes | 1 to 120 characters. |
email | string | Yes | A valid email address. |
password | string | Yes | 12 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
| Status | Code | When |
|---|---|---|
| 403 | INVALID_SETUP_TOKEN | The setup token is wrong. |
| 409 | ALREADY_SET_UP | The panel already has an owner. |
| 422 | VALIDATION_ERROR | A field is invalid, such as a password under 12 characters. |
| 429 | RATE_LIMITED | More than 10 attempts in 15 minutes. |
Sign in
/api/v1/auth/loginChecks 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
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | The account's email address. |
password | string | Yes | The 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 changesResponse 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
| Status | Code | When |
|---|---|---|
| 401 | INVALID_CREDENTIALS | The email or password is wrong, or the account is deactivated. |
| 403 | ACCOUNT_SUSPENDED | A hosting customer's account is suspended or closed (said only after the right password). |
| 403 | IP_NOT_ALLOWED | The panel does not accept sign-ins from this address. |
| 429 | ACCOUNT_LOCKED | Five failed attempts in a row lock the account for 15 minutes. |
| 429 | RATE_LIMITED | More than 20 attempts from this address in 15 minutes. |
Complete two-factor sign-in
/api/v1/auth/login/2faThe 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
| Field | Type | Required | Description |
|---|---|---|---|
challengeToken | string | Yes | From the sign-in response. |
code | string | One of the two | The current 6-digit code. |
recoveryCode | string | One of the two | A 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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHENTICATED | The challenge expired. Sign in again. |
| 401 | INVALID_CODE | The code is wrong, or the recovery code was already used. |
| 403 | ACCOUNT_SUSPENDED, IP_NOT_ALLOWED | As for Sign in. |
| 422 | VALIDATION_ERROR | Neither or both of code and recoveryCode were sent. |
| 429 | ACCOUNT_LOCKED | Too many failed attempts. |
Sign in with a billing link
/api/v1/auth/ssoExchanges 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
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | The token from the link. |
Response 200 OK. Sets the vp_session cookie and returns the same data as Sign in.
Errors
| Status | Code | When |
|---|---|---|
| 401 | LOGIN_LINK_INVALID | The link expired, was already used, or its account is deactivated. |
Get the current identity
/api/v1/auth/meWho 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,
permissionsare the overlap of the token's scopes and its owner's permissions,apiTokennames the token andcsrfTokenisnull. - With a session,
csrfTokenis the token to send asX-CSRF-TokenandapiTokenisnull. - With a plugin token,
userisnullandpluginnames the plugin and its scopes. recoveryCodesLeftisnullwhen two-factor sign-in is off.
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHENTICATED | No valid session or token. |
Sign out
/api/v1/auth/logoutEnds 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
/api/v1/auth/passwordChanges the signed-in person's password and signs out their other sessions.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
currentPassword | string | Yes | The password in use now. |
newPassword | string | Yes | 12 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
| Status | Code | When |
|---|---|---|
| 422 | VALIDATION_ERROR | currentPassword is incorrect, or newPassword is too short. |
Start two-factor setup
/api/v1/auth/2fa/setupCreates 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
| Status | Code | When |
|---|---|---|
| 409 | TWO_FACTOR_ALREADY_ENABLED | Two-factor sign-in is already on. |
Turn on two-factor sign-in
/api/v1/auth/2fa/enableConfirms 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
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The 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
| Status | Code | When |
|---|---|---|
| 400 | BAD_REQUEST | Setup was not started. |
| 409 | TWO_FACTOR_ALREADY_ENABLED | Two-factor sign-in is already on. |
| 422 | VALIDATION_ERROR | The code is not valid. |
Turn off two-factor sign-in
/api/v1/auth/2fa/disableTurns two-factor sign-in off for the signed-in person and deletes their recovery codes. Needs the password and a current code.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
password | string | Yes | The account's password. |
code | string | Yes | The current 6-digit code. |
Response 200 OK with data: null.
Errors
| Status | Code | When |
|---|---|---|
| 400 | BAD_REQUEST | Two-factor sign-in is not on. |
| 422 | VALIDATION_ERROR | The password or code is incorrect (details names which). |
Replace recovery codes
/api/v1/auth/2fa/recovery-codesMakes 10 new recovery codes. The old ones stop working.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
password | string | Yes | The account's password. |
code | string | Yes | The current 6-digit code. |
Response 200 OK with data.recoveryCodes, as for Turn on two-factor sign-in.
Errors
| Status | Code | When |
|---|---|---|
| 400 | BAD_REQUEST | Two-factor sign-in is not on. |
| 422 | VALIDATION_ERROR | The password or code is incorrect. |
List your sessions
/api/v1/auth/sessionsThe 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
/api/v1/auth/sessions/sign-out-othersEnds 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
/api/v1/auth/sessions/:idEnds one of the signed-in person's other sessions.
Response 200 OK with data: null.
Errors
| Status | Code | When |
|---|---|---|
| 400 | BAD_REQUEST | It is the current session. Use Sign out. |
| 404 | NOT_FOUND | No such active session of yours. |
Request a password reset
/api/v1/auth/password-reset/requestThe "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
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | The 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
| Status | Code | When |
|---|---|---|
| 409 | EMAIL_OFF | The panel cannot send email. An administrator can issue a reset link instead. |
| 429 | RATE_LIMITED | More than 20 requests from this address in 15 minutes. |
Inspect a reset or invite link
/api/v1/auth/password-reset/inspectSays 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
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | The 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
| Status | Code | When |
|---|---|---|
| 400 | INVALID_RESET_TOKEN | The link is invalid or has expired. |
Set a password from a link
/api/v1/auth/password-reset/completeSets the account's password from an invite or reset link and signs out its existing sessions. The link stops working.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | The token from the link. |
password | string | Yes | 12 to 256 characters. |
Response 200 OK
{ "success": true, "data": null, "message": "Password set. You can sign in now.", "requestId": "…" }Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_RESET_TOKEN | The link is invalid, expired or already used. |
| 422 | VALIDATION_ERROR | The password is too short. |
API overview
The VaultPanel REST API at a glance, covering base URL, authentication, the response envelope, errors, pagination, rate limits and background jobs.
API tokens
Create, list and revoke VaultPanel API tokens, and the scopes that decide which permissions a token carries on behalf of its owner.