# Security

URL: https://docs.vaultpanel.net/api-reference/security

> API reference for server firewalls, SSH settings and keys, Fail2ban, security updates, the login message, panel access by address, two-factor policy and sessions.

Each server change on this page is a job for the server's agent, which checks it again and refuses anything that would lock people out. The panel adds what only it knows: the port people reach the panel on (when the panel runs on that server, returned as `protectedPorts`) and your own address, so a firewall rule cannot block you. The panel-wide endpoints at the end set who may reach the panel, the two-factor policy, and signed-in sessions.

For the concepts, see [Security](https://docs.vaultpanel.net/guides/security), [Firewall](https://docs.vaultpanel.net/guides/security/firewall), [SSH](https://docs.vaultpanel.net/guides/security/ssh) and [Fail2ban and updates](https://docs.vaultpanel.net/guides/security/fail2ban-and-updates).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/security/overview` | [Get the security overview](https://docs.vaultpanel.net/api-reference/security#get-the-security-overview) |
| GET | `/api/v1/security/servers/:id` | [Get a server's security](https://docs.vaultpanel.net/api-reference/security#get-a-servers-security) |
| PUT | `/api/v1/security/servers/:id/firewall` | [Turn the firewall on or off](https://docs.vaultpanel.net/api-reference/security#turn-the-firewall-on-or-off) |
| POST | `/api/v1/security/servers/:id/firewall/rules` | [Add a firewall rule](https://docs.vaultpanel.net/api-reference/security#add-a-firewall-rule) |
| POST | `/api/v1/security/servers/:id/firewall/rules/delete` | [Delete a firewall rule](https://docs.vaultpanel.net/api-reference/security#delete-a-firewall-rule) |
| PUT | `/api/v1/security/servers/:id/firewall/default` | [Set the firewall defaults](https://docs.vaultpanel.net/api-reference/security#set-the-firewall-defaults) |
| PUT | `/api/v1/security/servers/:id/ssh` | [Change SSH settings](https://docs.vaultpanel.net/api-reference/security#change-ssh-settings) |
| PUT | `/api/v1/security/servers/:id/ssh/ports` | [Change SSH ports](https://docs.vaultpanel.net/api-reference/security#change-ssh-ports) |
| POST | `/api/v1/security/servers/:id/ssh/keys` | [Add an SSH key](https://docs.vaultpanel.net/api-reference/security#add-an-ssh-key) |
| POST | `/api/v1/security/servers/:id/ssh/keys/delete` | [Remove an SSH key](https://docs.vaultpanel.net/api-reference/security#remove-an-ssh-key) |
| PUT | `/api/v1/security/servers/:id/login-banner` | [Set the login message](https://docs.vaultpanel.net/api-reference/security#set-the-login-message) |
| PUT | `/api/v1/security/servers/:id/fail2ban` | [Configure Fail2ban](https://docs.vaultpanel.net/api-reference/security#configure-fail2ban) |
| POST | `/api/v1/security/servers/:id/fail2ban/unban` | [Unban an address](https://docs.vaultpanel.net/api-reference/security#unban-an-address) |
| PUT | `/api/v1/security/servers/:id/updates` | [Turn automatic updates on or off](https://docs.vaultpanel.net/api-reference/security#turn-automatic-updates-on-or-off) |
| POST | `/api/v1/security/servers/:id/updates/install` | [Install security updates](https://docs.vaultpanel.net/api-reference/security#install-security-updates) |
| GET | `/api/v1/security/panel-access` | [Get panel access](https://docs.vaultpanel.net/api-reference/security#get-panel-access) |
| PUT | `/api/v1/security/panel-access` | [Set panel access](https://docs.vaultpanel.net/api-reference/security#set-panel-access) |
| GET | `/api/v1/security/authentication` | [Get the sign-in policy](https://docs.vaultpanel.net/api-reference/security#get-the-sign-in-policy) |
| PUT | `/api/v1/security/authentication` | [Set the two-factor policy](https://docs.vaultpanel.net/api-reference/security#set-the-two-factor-policy) |
| GET | `/api/v1/security/sessions` | [List sessions](https://docs.vaultpanel.net/api-reference/security#list-sessions) |
| DELETE | `/api/v1/security/sessions/:id` | [Sign out a session](https://docs.vaultpanel.net/api-reference/security#sign-out-a-session) |

## Server changes are jobs

Every `PUT` and `POST` under `/security/servers/:id` returns `202 Accepted` with the queued job as `data`. Wait for it with [`GET /api/v1/jobs/:id`](https://docs.vaultpanel.net/api-reference/jobs) or `panel.jobs.wait()`; its `output` and `error` say what the agent did.

```json
{
  "success": true,
  "data": {
    "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "type": "FIREWALL_RULE_ADD",
    "serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
    "status": "queued",
    "params": { "action": "allow", "protocol": "tcp", "port": "8080", "source": "203.0.113.0/24", "protectedPorts": [8090] },
    "resource": null,
    "attempts": 0,
    "output": null,
    "error": null,
    "createdAt": "2026-11-10T10:20:00.000Z"
  },
  "message": "Adding the rule",
  "requestId": "…"
}
```

These errors can come from any server change:

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No server with this id. |
| 409 | `SERVER_NOT_READY` | The server has no connected agent yet. |
| 409 | `AGENT_OUTDATED` | The agent cannot run this operation. Outgoing rules, the outgoing default, SSH ports and keys for accounts other than `root` need agent 0.34.0 or newer. |
| 409 | `DUPLICATE_OPERATION` | The same change is already queued or running (`details.jobId`). |
| 422 | `VALIDATION_ERROR` | A field is invalid. |

## Get the security overview

`GET /api/v1/security/overview` — Permission: security.read — Token scope: read

Returns every server with the security summary its agent last reported, the checks derived from it and a score: `passed` of `total` checks (checks with status `info` are not counted). `supported` is `false` when the agent cannot report security.

**Example request**

**cURL**

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

**JavaScript**

```js
const { items } = await panel.security.overview();
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
        "name": "web-1",
        "status": "online",
        "isLocal": true,
        "agentVersion": "0.41.0",
        "supported": true,
        "protectedPorts": [8090],
        "checkedAt": "2026-11-10T10:00:00.000Z",
        "checks": [
          { "key": "firewall", "label": "Firewall", "status": "ok", "detail": "On, 4 rules", "fix": "firewall" },
          { "key": "ssh_root", "label": "Root sign-in over SSH", "status": "warning", "detail": "Root can sign in with a password, the account attackers try first", "fix": "ssh" }
        ],
        "passed": 5,
        "total": 6
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## Get a server's security

`GET /api/v1/security/servers/:id` — Permission: security.read — Token scope: read

Returns one server's reported `summary` and `checks`, `protectedPorts`, `advanced` (the agent supports outgoing rules, SSH ports and keys for other accounts) and `yourAddress`, the address the panel sees your request from. For the full live state of the server (every firewall rule, SSH keys, banned addresses), run the `SECURITY_STATUS` operation with [`POST /api/v1/servers/:id/jobs`](https://docs.vaultpanel.net/api-reference/servers).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const security = await panel.security.server(serverId);
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "id": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
    "name": "web-1",
    "supported": true,
    "advanced": true,
    "protectedPorts": [8090],
    "summary": { "checkedAt": "2026-11-10T10:00:00.000Z" },
    "checks": [],
    "yourAddress": "198.51.100.7"
  },
  "message": "OK",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No server with this id. |

## Turn the firewall on or off

`PUT /api/v1/security/servers/:id/firewall` — Permission: security.manage — Token scope: servers

Turns UFW on (`FIREWALL_ENABLE`, keeping the panel's port reachable) or off (`FIREWALL_DISABLE`).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | Yes | `true` turns the firewall on. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/firewall \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

**JavaScript**

```js
const job = await panel.security.setFirewall(serverId, { enabled: true });
```

**Response** `202 Accepted`: the job, message `Turning the firewall on` or `Turning the firewall off`.

## Add a firewall rule

`POST /api/v1/security/servers/:id/firewall/rules` — Permission: security.manage — Token scope: servers

Adds a UFW rule. An incoming rule has a `source`; an outgoing rule (agent 0.34.0 or newer) has a `destination`.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | Yes | `allow`, `limit` (allow, but block an address that opens 6 or more connections in 30 seconds), `deny` (drop silently) or `reject` (refuse and tell the sender). |
| `direction` | string | No | `in` (default) or `out`. |
| `protocol` | string | No | `tcp` (default), `udp` or `any`. Lists and ranges of ports need `tcp` or `udp`. |
| `port` | string | No | A port, a list (`80,443`) or a range (`6000:6010`), up to 100 characters. |
| `source` | string | No | Incoming rules: an address or network. Default `any`. |
| `destination` | string | No | Outgoing rules: an address or network. Default `any`. |
| `comment` | string | No | Up to 60 characters. |

Give a port, an address, or both.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/firewall/rules \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "allow", "protocol": "tcp", "port": "8080", "source": "203.0.113.0/24", "comment": "Office" }'
```

**JavaScript**

```js
const job = await panel.security.addFirewallRule(serverId, {
  action: 'allow',
  protocol: 'tcp',
  port: '8080',
  source: '203.0.113.0/24',
  comment: 'Office',
});
```

**Response** `202 Accepted`: the job, message `Adding the rule`.

**Errors** (besides those of [every server change](https://docs.vaultpanel.net/api-reference/security#server-changes-are-jobs))

| Status | Code | When |
| --- | --- | --- |
| 409 | `LOCKOUT_REFUSED` | An incoming `deny` or `reject` rule whose source includes your own address. |

## Delete a firewall rule

`POST /api/v1/security/servers/:id/firewall/rules/delete` — Permission: security.manage — Token scope: servers

Deletes the rule that matches the fields given: the same fields as [Add a firewall rule](https://docs.vaultpanel.net/api-reference/security#add-a-firewall-rule) without `comment`, plus `app` for a rule UFW created for an application profile (up to 64 characters).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/firewall/rules/delete \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "allow", "protocol": "tcp", "port": "8080", "source": "203.0.113.0/24" }'
```

**JavaScript**

```js
const job = await panel.security.removeFirewallRule(serverId, {
  action: 'allow',
  protocol: 'tcp',
  port: '8080',
  source: '203.0.113.0/24',
});
```

**Response** `202 Accepted`: the job, message `Deleting the rule`.

## Set the firewall defaults

`PUT /api/v1/security/servers/:id/firewall/default` — Permission: security.manage — Token scope: servers

Sets what happens to traffic no rule matches. Give at least one of the two.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `incoming` | string | No | `deny` (recommended), `reject` or `allow`. |
| `outgoing` | string | No | `allow` (usual), `deny` or `reject`. Needs agent 0.34.0 or newer. |

When outgoing connections are denied by default, the agent keeps what the server needs allowed: reaching the panel, name lookups, updates, the clock and mail.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/firewall/default \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "incoming": "deny" }'
```

**JavaScript**

```js
const job = await panel.request('PUT', `/security/servers/${serverId}/firewall/default`, {
  body: { incoming: 'deny' },
});
```

**Response** `202 Accepted`: the job, message `Changing the default`.

## Change SSH settings

`PUT /api/v1/security/servers/:id/ssh` — Permission: security.manage — Token scope: servers

Changes the SSH server's sign-in settings (`SSH_CONFIGURE`). Send all three fields.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `permitRootLogin` | string | Yes | `yes`, `prohibit-password` (keys only) or `no`. |
| `passwordAuthentication` | boolean | Yes | Allow sign-in with a password. |
| `maxAuthTries` | integer | Yes | 1 to 10. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/ssh \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "permitRootLogin": "prohibit-password", "passwordAuthentication": false, "maxAuthTries": 3 }'
```

**JavaScript**

```js
const job = await panel.request('PUT', `/security/servers/${serverId}/ssh`, {
  body: { permitRootLogin: 'prohibit-password', passwordAuthentication: false, maxAuthTries: 3 },
});
```

**Response** `202 Accepted`: the job, message `Applying SSH settings`.

## Change SSH ports

`PUT /api/v1/security/servers/:id/ssh/ports` — Permission: security.manage — Token scope: servers

Sets the ports SSH listens on: one, or two while you move to a new port. Needs agent 0.34.0 or newer.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ports` | integer[] | Yes | 1 or 2 different ports from 1 to 65535. Not 80 or 443, and not the panel's own port. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/ssh/ports \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ports": [22, 2222] }'
```

**JavaScript**

```js
const job = await panel.request('PUT', `/security/servers/${serverId}/ssh/ports`, {
  body: { ports: [22, 2222] },
});
```

**Response** `202 Accepted`: the job, message `Changing the SSH port`.

**Errors** (besides those of [every server change](https://docs.vaultpanel.net/api-reference/security#server-changes-are-jobs))

| Status | Code | When |
| --- | --- | --- |
| 422 | `VALIDATION_ERROR` | A port is the one people reach the panel on, is reserved, or appears twice. |

## Add an SSH key

`POST /api/v1/security/servers/:id/ssh/keys` — Permission: security.manage — Token scope: servers

Adds a public key to an account's `authorized_keys` (`SSH_KEY_ADD`).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | Yes | One public key line, such as the contents of `~/.ssh/id_ed25519.pub`. Types: `ssh-ed25519`, `ssh-rsa`, `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, `sk-ssh-ed25519@openssh.com`, `sk-ecdsa-sha2-nistp256@openssh.com`. Options in front of the key are not accepted. |
| `user` | string | No | The Linux account. Default `root`; other accounts need agent 0.34.0 or newer. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/ssh/keys \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{ \"key\": \"$(cat ~/.ssh/id_ed25519.pub)\" }"
```

**JavaScript**

```js
import { readFile } from 'node:fs/promises';

const key = (await readFile(`${process.env.HOME}/.ssh/id_ed25519.pub`, 'utf8')).trim();
const job = await panel.request('POST', `/security/servers/${serverId}/ssh/keys`, { body: { key } });
```

**Response** `202 Accepted`: the job, message `Adding the key`.

## Remove an SSH key

`POST /api/v1/security/servers/:id/ssh/keys/delete` — Permission: security.manage — Token scope: servers

Removes a key by its fingerprint (`SSH_KEY_REMOVE`). The `SECURITY_STATUS` operation lists each account's keys with their fingerprints.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fingerprint` | string | Yes | The key's SHA256 fingerprint: `SHA256:` and 43 base64 characters. |
| `user` | string | No | The Linux account. Default `root`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/ssh/keys/delete \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "fingerprint": "SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8" }'
```

**JavaScript**

```js
const job = await panel.request('POST', `/security/servers/${serverId}/ssh/keys/delete`, {
  body: { fingerprint: 'SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8' },
});
```

**Response** `202 Accepted`: the job, message `Removing the key`.

## Set the login message

`PUT /api/v1/security/servers/:id/login-banner` — Permission: security.manage — Token scope: servers

Chooses what SSH logins and the browser terminal show: only the VaultPanel banner (with this server's name and the panel's address), or the system's own welcome message (`LOGIN_BANNER_SET`, agent 0.21.0 or newer).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `vaultpanelOnly` | boolean | Yes | `true` shows only the VaultPanel banner; `false` brings back the system's message. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/login-banner \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "vaultpanelOnly": false }'
```

**JavaScript**

```js
const job = await panel.request('PUT', `/security/servers/${serverId}/login-banner`, {
  body: { vaultpanelOnly: false },
});
```

**Response** `202 Accepted`: the job, message `Changing the login message`.

## Configure Fail2ban

`PUT /api/v1/security/servers/:id/fail2ban` — Permission: security.manage — Token scope: servers

Turns Fail2ban's SSH protection on or off and sets its limits (`FAIL2BAN_CONFIGURE`).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | Yes | Turn Fail2ban on or off. |
| `maxRetry` | integer | No | Failed attempts before a ban: 1 to 20, default 5. |
| `findTimeMinutes` | integer | No | The window those attempts are counted in: 1 to 1440, default 10. |
| `banTimeMinutes` | integer | No | How long a ban lasts: 1 to 43200, default 60. |
| `ignoreIps` | string[] | No | Up to 20 addresses or networks never banned. Default none. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/fail2ban \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "maxRetry": 5, "findTimeMinutes": 10, "banTimeMinutes": 60, "ignoreIps": ["203.0.113.0/24"] }'
```

**JavaScript**

```js
const job = await panel.request('PUT', `/security/servers/${serverId}/fail2ban`, {
  body: { enabled: true, maxRetry: 5, findTimeMinutes: 10, banTimeMinutes: 60, ignoreIps: ['203.0.113.0/24'] },
});
```

**Response** `202 Accepted`: the job, message `Applying Fail2ban settings`.

## Unban an address

`POST /api/v1/security/servers/:id/fail2ban/unban` — Permission: security.manage — Token scope: servers

Lifts Fail2ban's ban on one address (`FAIL2BAN_UNBAN`).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ip` | string | Yes | One IP address (not a network). |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/fail2ban/unban \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ip": "198.51.100.7" }'
```

**JavaScript**

```js
const job = await panel.request('POST', `/security/servers/${serverId}/fail2ban/unban`, {
  body: { ip: '198.51.100.7' },
});
```

**Response** `202 Accepted`: the job, message `Unblocking the address`.

## Turn automatic updates on or off

`PUT /api/v1/security/servers/:id/updates` — Permission: security.manage — Token scope: servers

Turns automatic security updates (unattended-upgrades) on or off (`AUTO_UPDATES_CONFIGURE`).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | Yes | `true` installs security updates automatically. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/updates \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

**JavaScript**

```js
const job = await panel.request('PUT', `/security/servers/${serverId}/updates`, { body: { enabled: true } });
```

**Response** `202 Accepted`: the job, message `Changing automatic updates`.

## Install security updates

`POST /api/v1/security/servers/:id/updates/install` — Permission: security.manage — Token scope: servers

Installs the pending security updates now (`SECURITY_UPDATES_INSTALL`). No body.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/updates/install \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const job = await panel.security.installUpdates(serverId);
await panel.jobs.wait(job.id);
```

**Response** `202 Accepted`: the job, message `Installing security updates`.

## Get panel access

`GET /api/v1/security/panel-access` — Permission: settings.manage — Token scope: full

Returns the list of addresses allowed to use the panel, whether the list is on, and who it applies to. `disabledByEnv` is `true` when `VAULTPANEL_PANEL_ACCESS=off` in the panel's `.env` turns the check off. Requests from addresses not on an enabled list are refused with `403 IP_NOT_ALLOWED` (`details.address`). Requests from the server itself (loopback) are always allowed. See [Panel access](https://docs.vaultpanel.net/guides/security/panel-access).

**Example request**

**cURL**

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

**JavaScript**

```js
const access = await panel.request('GET', '/security/panel-access');
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "enabled": true,
    "scope": "staff",
    "addresses": [{ "address": "203.0.113.0/24", "note": "Office" }],
    "yourAddress": "203.0.113.25",
    "disabledByEnv": false
  },
  "message": "OK",
  "requestId": "…"
}
```

## Set panel access

`PUT /api/v1/security/panel-access` — Permission: settings.manage — Token scope: full

Saves the list. It cannot be turned on, or saved while on, unless your own address is in it.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | Yes | Turn the list on. Needs at least one address. |
| `scope` | string | No | `everyone` (default: staff and hosting customers) or `staff` (customers sign in from anywhere). |
| `addresses` | object[] | Yes | Up to 50 entries `{ address, note }`: an IP address or network such as `203.0.113.0/24`, each once, and an optional note of up to 60 characters. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/panel-access \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "scope": "staff", "addresses": [{ "address": "203.0.113.0/24", "note": "Office" }] }'
```

**JavaScript**

```js
await panel.request('PUT', '/security/panel-access', {
  body: { enabled: true, scope: 'staff', addresses: [{ address: '203.0.113.0/24', note: 'Office' }] },
});
```

**Response** `200 OK`: the saved settings as in [Get panel access](https://docs.vaultpanel.net/api-reference/security#get-panel-access), message `Panel access saved`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `LOCKOUT_REFUSED` | Your own address is not in the list. |
| 422 | `VALIDATION_ERROR` | Turned on with no addresses, an invalid address, or an address twice. |

## Get the sign-in policy

`GET /api/v1/security/authentication` — Permission: settings.manage — Token scope: full

Returns the two-factor policy and every user's two-factor state, recovery codes left and active sessions.

**Example request**

**cURL**

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

**JavaScript**

```js
const { twoFactorPolicy, users } = await panel.request('GET', '/security/authentication');
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "twoFactorPolicy": "admins",
    "users": [
      {
        "id": "3c4d5e6f-…",
        "email": "owner@example.com",
        "name": "Sam Owner",
        "role": "owner",
        "isActive": true,
        "twoFactorEnabled": true,
        "recoveryCodesLeft": 9,
        "activeSessions": 2,
        "lastLoginAt": "2026-11-10T08:00:00.000Z"
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## Set the two-factor policy

`PUT /api/v1/security/authentication` — Permission: settings.manage — Token scope: full

Sets who must use two-factor sign-in. People the policy covers who have not set it up are sent to set it up at their next request: every other route answers `403 TWO_FACTOR_SETUP_REQUIRED` until they do. See [Sign-in and two-factor](https://docs.vaultpanel.net/guides/security/sign-in-and-two-factor).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `twoFactorPolicy` | string | Yes | `off` (each person decides), `admins` (owners and admins must) or `all` (every account must). |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/authentication \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "twoFactorPolicy": "admins" }'
```

**JavaScript**

```js
await panel.request('PUT', '/security/authentication', { body: { twoFactorPolicy: 'admins' } });
```

**Response** `200 OK`: the same data as [Get the sign-in policy](https://docs.vaultpanel.net/api-reference/security#get-the-sign-in-policy), message `Sign-in policy saved`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `TWO_FACTOR_REQUIRED_FIRST` | Turning the policy on before your own account uses two-factor sign-in. |
| 422 | `VALIDATION_ERROR` | Unknown policy. |

## List sessions

`GET /api/v1/security/sessions` — Permission: users.manage — Token scope: full

Returns everyone's signed-in sessions, most recently used first (up to 500). `current` marks the session making the request. Your own sessions are also at `GET /api/v1/auth/sessions`; see [Authentication](https://docs.vaultpanel.net/api-reference/authentication).

**Example request**

**cURL**

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

**JavaScript**

```js
const { items } = await panel.request('GET', '/security/sessions');
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "8d9e0f1a-…",
        "user": { "id": "3c4d5e6f-…", "email": "owner@example.com", "name": "Sam Owner" },
        "ip": "198.51.100.7",
        "userAgent": "Mozilla/5.0 …",
        "createdAt": "2026-11-10T08:00:00.000Z",
        "lastSeenAt": "2026-11-10T10:20:00.000Z",
        "expiresAt": "2026-11-17T08:00:00.000Z",
        "current": false
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## Sign out a session

`DELETE /api/v1/security/sessions/:id` — Permission: users.manage — Token scope: full

Ends someone's session. You cannot end a session of someone whose role ranks above yours, nor the session you are using (sign out instead).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/security/sessions/8d9e0f1a-2b3c-4d5e-8f6a-7b8c9d0e1f2a \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.request('DELETE', `/security/sessions/${sessionId}`);
```

**Response** `200 OK`: `data` is `null`, message `Session signed out`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 400 | `BAD_REQUEST` | The session is the one you are using. |
| 403 | `FORBIDDEN` | The session's user has a higher role than yours. |
| 404 | `NOT_FOUND` | No active session with this id. |
