# Authentication

URL: https://docs.vaultpanel.net/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.

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](https://docs.vaultpanel.net/api-reference/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](https://docs.vaultpanel.net/api-reference/plugins). |
| Billing API key | `vpk_…` | Billing systems | Only on `/billing`. See [Billing](https://docs.vaultpanel.net/api-reference/billing). |
| Agent signature | Signed headers | Server agents | Only on `/agent`. See [Agent](https://docs.vaultpanel.net/api-reference/agent). |
| Webhook token | In the URL | Git hosts | Only on `/hooks/deploy/:token`. See [Git push hooks](https://docs.vaultpanel.net/api-reference/applications#git-push-hook). |

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](https://docs.vaultpanel.net/guides/security/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](https://docs.vaultpanel.net/guides/security/panel-access).

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/auth/setup` | [Get setup status](https://docs.vaultpanel.net/api-reference/authentication#get-setup-status) |
| POST | `/api/v1/auth/setup` | [Create the owner account](https://docs.vaultpanel.net/api-reference/authentication#create-the-owner-account) |
| POST | `/api/v1/auth/login` | [Sign in](https://docs.vaultpanel.net/api-reference/authentication#sign-in) |
| POST | `/api/v1/auth/login/2fa` | [Complete two-factor sign-in](https://docs.vaultpanel.net/api-reference/authentication#complete-two-factor-sign-in) |
| POST | `/api/v1/auth/sso` | [Sign in with a billing link](https://docs.vaultpanel.net/api-reference/authentication#sign-in-with-a-billing-link) |
| GET | `/api/v1/auth/me` | [Get the current identity](https://docs.vaultpanel.net/api-reference/authentication#get-the-current-identity) |
| POST | `/api/v1/auth/logout` | [Sign out](https://docs.vaultpanel.net/api-reference/authentication#sign-out) |
| POST | `/api/v1/auth/password` | [Change your password](https://docs.vaultpanel.net/api-reference/authentication#change-your-password) |
| POST | `/api/v1/auth/2fa/setup` | [Start two-factor setup](https://docs.vaultpanel.net/api-reference/authentication#start-two-factor-setup) |
| POST | `/api/v1/auth/2fa/enable` | [Turn on two-factor sign-in](https://docs.vaultpanel.net/api-reference/authentication#turn-on-two-factor-sign-in) |
| POST | `/api/v1/auth/2fa/disable` | [Turn off two-factor sign-in](https://docs.vaultpanel.net/api-reference/authentication#turn-off-two-factor-sign-in) |
| POST | `/api/v1/auth/2fa/recovery-codes` | [Replace recovery codes](https://docs.vaultpanel.net/api-reference/authentication#replace-recovery-codes) |
| GET | `/api/v1/auth/sessions` | [List your sessions](https://docs.vaultpanel.net/api-reference/authentication#list-your-sessions) |
| POST | `/api/v1/auth/sessions/sign-out-others` | [Sign out other sessions](https://docs.vaultpanel.net/api-reference/authentication#sign-out-other-sessions) |
| DELETE | `/api/v1/auth/sessions/:id` | [Sign out a session](https://docs.vaultpanel.net/api-reference/authentication#sign-out-a-session) |
| POST | `/api/v1/auth/password-reset/request` | [Request a password reset](https://docs.vaultpanel.net/api-reference/authentication#request-a-password-reset) |
| POST | `/api/v1/auth/password-reset/inspect` | [Inspect a reset or invite link](https://docs.vaultpanel.net/api-reference/authentication#inspect-a-reset-or-invite-link) |
| POST | `/api/v1/auth/password-reset/complete` | [Set a password from a link](https://docs.vaultpanel.net/api-reference/authentication#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

`GET /api/v1/auth/setup` — Auth: public

Whether the panel still needs its first owner, and whether the sign-in page can offer "Forgot password?" (true when [panel email](https://docs.vaultpanel.net/guides/dns-and-email/panel-email) is set up).

**Example request**

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

**Response** `200 OK`

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

## Create the owner account

`POST /api/v1/auth/setup` — Auth: public

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

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

```bash
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](https://docs.vaultpanel.net/api-reference/authentication#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

`POST /api/v1/auth/login` — Auth: public

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](https://docs.vaultpanel.net/api-reference/authentication#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**

```bash
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"}'
```

**JavaScript**

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

```json
{
  "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

```json
{ "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

`POST /api/v1/auth/login/2fa` — Auth: public

The second step of sign-in. Send the challenge from [Sign in](https://docs.vaultpanel.net/api-reference/authentication#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**

```bash
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](https://docs.vaultpanel.net/api-reference/authentication#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](https://docs.vaultpanel.net/api-reference/authentication#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

`POST /api/v1/auth/sso` — Auth: public

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](https://docs.vaultpanel.net/api-reference/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](https://docs.vaultpanel.net/api-reference/authentication#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

`GET /api/v1/auth/me`

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

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

**JavaScript**

```js
const me = await panel.me();
```

**Response** `200 OK`

```json
{
  "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**

| Status | Code | When |
| --- | --- | --- |
| 401 | `UNAUTHENTICATED` | No valid session or token. |

## Sign out

`POST /api/v1/auth/logout` — Auth: session

Ends the current session and clears the cookie.

**Example request**

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

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

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

`POST /api/v1/auth/2fa/setup` — Auth: session

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](https://docs.vaultpanel.net/api-reference/authentication#turn-on-two-factor-sign-in).

**Response** `200 OK`

```json
{ "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

`POST /api/v1/auth/2fa/enable` — Auth: session

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | The current 6-digit code. |

**Response** `200 OK`

```json
{ "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

`POST /api/v1/auth/2fa/disable` — Auth: session

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

| 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

`POST /api/v1/auth/2fa/recovery-codes` — Auth: session

Makes 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](https://docs.vaultpanel.net/api-reference/authentication#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

`GET /api/v1/auth/sessions` — Auth: session

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

**Response** `200 OK`

```json
{
  "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

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

**Response** `200 OK`

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

## Sign out a session

`DELETE /api/v1/auth/sessions/:id` — Auth: session

Ends 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](https://docs.vaultpanel.net/api-reference/authentication#sign-out). |
| 404 | `NOT_FOUND` | No such active session of yours. |

## Request a password reset

`POST /api/v1/auth/password-reset/request` — Auth: public

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](https://docs.vaultpanel.net/guides/dns-and-email/panel-email).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | The account's email address. |

**Response** `202 Accepted`

```json
{ "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](https://docs.vaultpanel.net/api-reference/users-and-roles#issue-a-password-reset-link) instead. |
| 429 | `RATE_LIMITED` | More than 20 requests from this address in 15 minutes. |

## Inspect a reset or invite link

`POST /api/v1/auth/password-reset/inspect` — Auth: public

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | Yes | The token from the link. |

**Response** `200 OK`

```json
{ "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

`POST /api/v1/auth/password-reset/complete` — Auth: public

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

```json
{ "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. |
