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.

Last updated

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, Firewall, SSH and Fail2ban and updates.

MethodPathDescription
GET/api/v1/security/overviewGet the security overview
GET/api/v1/security/servers/:idGet a server's security
PUT/api/v1/security/servers/:id/firewallTurn the firewall on or off
POST/api/v1/security/servers/:id/firewall/rulesAdd a firewall rule
POST/api/v1/security/servers/:id/firewall/rules/deleteDelete a firewall rule
PUT/api/v1/security/servers/:id/firewall/defaultSet the firewall defaults
PUT/api/v1/security/servers/:id/sshChange SSH settings
PUT/api/v1/security/servers/:id/ssh/portsChange SSH ports
POST/api/v1/security/servers/:id/ssh/keysAdd an SSH key
POST/api/v1/security/servers/:id/ssh/keys/deleteRemove an SSH key
PUT/api/v1/security/servers/:id/login-bannerSet the login message
PUT/api/v1/security/servers/:id/fail2banConfigure Fail2ban
POST/api/v1/security/servers/:id/fail2ban/unbanUnban an address
PUT/api/v1/security/servers/:id/updatesTurn automatic updates on or off
POST/api/v1/security/servers/:id/updates/installInstall security updates
GET/api/v1/security/panel-accessGet panel access
PUT/api/v1/security/panel-accessSet panel access
GET/api/v1/security/authenticationGet the sign-in policy
PUT/api/v1/security/authenticationSet the two-factor policy
GET/api/v1/security/sessionsList sessions
DELETE/api/v1/security/sessions/:idSign 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 or panel.jobs.wait(); its output and error say what the agent did.

{
  "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:

StatusCodeWhen
404NOT_FOUNDNo server with this id.
409SERVER_NOT_READYThe server has no connected agent yet.
409AGENT_OUTDATEDThe 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.
409DUPLICATE_OPERATIONThe same change is already queued or running (details.jobId).
422VALIDATION_ERRORA field is invalid.

Get the security overview

GET/api/v1/security/overview
Auth
Session cookie (+ CSRF token) or API token
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 https://panel.example.com/api/v1/security/overview \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.security.overview();

Response 200 OK

{
  "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
Auth
Session cookie (+ CSRF token) or API token
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.

Example request

curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const security = await panel.security.server(serverId);

Response 200 OK

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

StatusCodeWhen
404NOT_FOUNDNo server with this id.

Turn the firewall on or off

PUT/api/v1/security/servers/:id/firewall
Auth
Session cookie (+ CSRF token) or API token
Permission
security.manage
Token scope
servers

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

Request body

FieldTypeRequiredDescription
enabledbooleanYestrue turns the firewall on.

Example request

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 }'
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
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
actionstringYesallow, 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).
directionstringNoin (default) or out.
protocolstringNotcp (default), udp or any. Lists and ranges of ports need tcp or udp.
portstringNoA port, a list (80,443) or a range (6000:6010), up to 100 characters.
sourcestringNoIncoming rules: an address or network. Default any.
destinationstringNoOutgoing rules: an address or network. Default any.
commentstringNoUp to 60 characters.

Give a port, an address, or both.

Example request

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" }'
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)

StatusCodeWhen
409LOCKOUT_REFUSEDAn incoming deny or reject rule whose source includes your own address.

Delete a firewall rule

POST/api/v1/security/servers/:id/firewall/rules/delete
Auth
Session cookie (+ CSRF token) or API token
Permission
security.manage
Token scope
servers

Deletes the rule that matches the fields given: the same fields as Add a firewall rule without comment, plus app for a rule UFW created for an application profile (up to 64 characters).

Example request

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" }'
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
Auth
Session cookie (+ CSRF token) or API token
Permission
security.manage
Token scope
servers

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

Request body

FieldTypeRequiredDescription
incomingstringNodeny (recommended), reject or allow.
outgoingstringNoallow (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 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" }'
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
Auth
Session cookie (+ CSRF token) or API token
Permission
security.manage
Token scope
servers

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

Request body

FieldTypeRequiredDescription
permitRootLoginstringYesyes, prohibit-password (keys only) or no.
passwordAuthenticationbooleanYesAllow sign-in with a password.
maxAuthTriesintegerYes1 to 10.

Example request

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 }'
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
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
portsinteger[]Yes1 or 2 different ports from 1 to 65535. Not 80 or 443, and not the panel's own port.

Example request

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] }'
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)

StatusCodeWhen
422VALIDATION_ERRORA 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
Auth
Session cookie (+ CSRF token) or API token
Permission
security.manage
Token scope
servers

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

Request body

FieldTypeRequiredDescription
keystringYesOne 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.
userstringNoThe Linux account. Default root; other accounts need agent 0.34.0 or newer.

Example request

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)\" }"
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
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
fingerprintstringYesThe key's SHA256 fingerprint: SHA256: and 43 base64 characters.
userstringNoThe Linux account. Default root.

Example request

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" }'
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
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
vaultpanelOnlybooleanYestrue shows only the VaultPanel banner; false brings back the system's message.

Example request

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 }'
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
Auth
Session cookie (+ CSRF token) or API token
Permission
security.manage
Token scope
servers

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

Request body

FieldTypeRequiredDescription
enabledbooleanYesTurn Fail2ban on or off.
maxRetryintegerNoFailed attempts before a ban: 1 to 20, default 5.
findTimeMinutesintegerNoThe window those attempts are counted in: 1 to 1440, default 10.
banTimeMinutesintegerNoHow long a ban lasts: 1 to 43200, default 60.
ignoreIpsstring[]NoUp to 20 addresses or networks never banned. Default none.

Example request

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"] }'
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
Auth
Session cookie (+ CSRF token) or API token
Permission
security.manage
Token scope
servers

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

Request body

FieldTypeRequiredDescription
ipstringYesOne IP address (not a network).

Example request

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" }'
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
Auth
Session cookie (+ CSRF token) or API token
Permission
security.manage
Token scope
servers

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

Request body

FieldTypeRequiredDescription
enabledbooleanYestrue installs security updates automatically.

Example request

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 }'
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
Auth
Session cookie (+ CSRF token) or API token
Permission
security.manage
Token scope
servers

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

Example request

curl https://panel.example.com/api/v1/security/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/updates/install \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
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
Auth
Session cookie (+ CSRF token) or API token
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.

Example request

curl https://panel.example.com/api/v1/security/panel-access \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const access = await panel.request('GET', '/security/panel-access');

Response 200 OK

{
  "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
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
enabledbooleanYesTurn the list on. Needs at least one address.
scopestringNoeveryone (default: staff and hosting customers) or staff (customers sign in from anywhere).
addressesobject[]YesUp 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 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" }] }'
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, message Panel access saved.

Errors

StatusCodeWhen
409LOCKOUT_REFUSEDYour own address is not in the list.
422VALIDATION_ERRORTurned on with no addresses, an invalid address, or an address twice.

Get the sign-in policy

GET/api/v1/security/authentication
Auth
Session cookie (+ CSRF token) or API token
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 https://panel.example.com/api/v1/security/authentication \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { twoFactorPolicy, users } = await panel.request('GET', '/security/authentication');

Response 200 OK

{
  "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
Auth
Session cookie (+ CSRF token) or API token
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.

Request body

FieldTypeRequiredDescription
twoFactorPolicystringYesoff (each person decides), admins (owners and admins must) or all (every account must).

Example request

curl https://panel.example.com/api/v1/security/authentication \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "twoFactorPolicy": "admins" }'
await panel.request('PUT', '/security/authentication', { body: { twoFactorPolicy: 'admins' } });

Response 200 OK: the same data as Get the sign-in policy, message Sign-in policy saved.

Errors

StatusCodeWhen
409TWO_FACTOR_REQUIRED_FIRSTTurning the policy on before your own account uses two-factor sign-in.
422VALIDATION_ERRORUnknown policy.

List sessions

GET/api/v1/security/sessions
Auth
Session cookie (+ CSRF token) or API token
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.

Example request

curl https://panel.example.com/api/v1/security/sessions \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.request('GET', '/security/sessions');

Response 200 OK

{
  "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
Auth
Session cookie (+ CSRF token) or API token
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 https://panel.example.com/api/v1/security/sessions/8d9e0f1a-2b3c-4d5e-8f6a-7b8c9d0e1f2a \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
await panel.request('DELETE', `/security/sessions/${sessionId}`);

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

Errors

StatusCodeWhen
400BAD_REQUESTThe session is the one you are using.
403FORBIDDENThe session's user has a higher role than yours.
404NOT_FOUNDNo active session with this id.