API Reference

Users and roles

API reference for panel users (invite, update, deactivate, reset links and two-factor resets), the built-in roles and the audit log.

Last updated

Staff accounts are managed under /users, roles are read from /roles and the audit log from /audit-logs. Hosting customers are accounts too, but they are created and managed under Hosting; /users leaves them out unless you filter by the customer role.

Roles and rank

Every user has one role. Routes check permissions, never role names. A role's rank decides who may manage whom: you can only assign roles at or below your own rank, and you cannot manage a user whose role ranks above yours.

RoleRankWhat it is for
owner40Full control of the panel, including other owners and the server terminal
admin30Manage servers, users (except owners) and settings
developer20View most things, deploy and restart apps and containers, back up, run cron jobs and routine operations, work on website files, and ask the AI assistant
viewer10Read-only access, and the AI assistant
customer5A hosting customer, limited to their own account. Given only by creating a customer

GET /roles returns each role's exact permissions. See Users and roles for the full permission list.

Endpoints

MethodPathDescription
GET/api/v1/usersList users
POST/api/v1/usersInvite a user
GET/api/v1/users/:idGet a user
PATCH/api/v1/users/:idUpdate a user
POST/api/v1/users/:id/password-resetIssue a password reset link
POST/api/v1/users/:id/2fa/resetReset two-factor sign-in
GET/api/v1/rolesList roles
GET/api/v1/audit-logsList audit log entries

The user object

{
  "id": "7b1e4d2a-9c3f-4e8b-a5d6-0f2c8e1b3a94",
  "email": "grace@example.com",
  "name": "Grace Hopper",
  "isActive": true,
  "twoFactorEnabled": false,
  "roles": ["developer"],
  "lastLoginAt": "2026-11-09T16:20:11.000Z",
  "createdAt": "2026-10-21T10:00:00.000Z",
  "updatedAt": "2026-11-09T16:20:11.000Z"
}

List users

GET/api/v1/users
Auth
Session cookie (+ CSRF token) or API token
Permission
users.read
Token scope
read

Staff accounts, newest first. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
searchstringNoMatches email or name.
statusstringNoactive or inactive.
rolestringNoowner, admin, developer, viewer or customer. Without it, customers are left out.
sortstringNocreatedAt (default), email, name or lastLoginAt.

Example request

curl "https://panel.example.com/api/v1/users?status=active&role=developer" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items, pagination } = await panel.users.list({ status: 'active', role: 'developer' });

Response 200 OK: { items: [user], pagination }.

Invite a user

POST/api/v1/users
Auth
Session cookie (+ CSRF token) or API token
Permission
users.manage
Token scope
full

Creates an account with no usable password and returns a one-time invite link, valid for 72 hours, where the person chooses their password. When panel email is set up the link is also emailed; it is returned either way, to hand over if the email does not arrive.

Request body

FieldTypeRequiredDescription
emailstringYesMust not belong to another user.
namestringYes1 to 120 characters.
rolestringYesowner, admin, developer or viewer, at or below your own role.

Example request

curl https://panel.example.com/api/v1/users \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"grace@example.com","name":"Grace Hopper","role":"developer"}'
const { user, inviteUrl, email } = await panel.users.invite({
  email: 'grace@example.com',
  name: 'Grace Hopper',
  role: 'developer',
});

Response 201 Created

{
  "success": true,
  "data": {
    "user": { "id": "7b1e4d2a-9c3f-4e8b-a5d6-0f2c8e1b3a94", "email": "grace@example.com", "name": "Grace Hopper", "isActive": true, "twoFactorEnabled": false, "roles": ["developer"], "lastLoginAt": null, "createdAt": "…", "updatedAt": "…" },
    "inviteUrl": "https://panel.example.com/reset-password#token=…",
    "inviteExpiresAt": "2026-11-13T09:30:00.000Z",
    "email": { "to": "grace@example.com", "sent": true }
  },
  "message": "User created. The invite link was emailed to grace@example.com.",
  "requestId": "…"
}

email is null when panel email is not set up, or { to, sent: false, error } when sending failed.

Errors

StatusCodeWhen
403FORBIDDENYou lack users.manage, the role ranks above yours, or the role is customer.
409CONFLICTA user with this email already exists.
422VALIDATION_ERRORA field is invalid.

Get a user

GET/api/v1/users/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
users.read
Token scope
read

Example request

curl https://panel.example.com/api/v1/users/7b1e4d2a-9c3f-4e8b-a5d6-0f2c8e1b3a94 \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const user = await panel.users.get(userId);

Response 200 OK with the user object.

Errors

StatusCodeWhen
404NOT_FOUNDNo such user.

Update a user

PATCH/api/v1/users/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
users.manage
Token scope
full

Renames a user, changes their role, or deactivates or reactivates them. Changing the role or deactivating signs the user out of every session at once, so the change applies immediately. Send at least one field.

Request body

FieldTypeRequiredDescription
namestringNo1 to 120 characters.
rolestringNoowner, admin, developer or viewer, at or below your own role.
isActivebooleanNofalse deactivates the account.

Example request

curl -X PATCH https://panel.example.com/api/v1/users/7b1e4d2a-9c3f-4e8b-a5d6-0f2c8e1b3a94 \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"isActive":false}'
const user = await panel.users.update(userId, { isActive: false });

Response 200 OK with the updated user object.

Errors

StatusCodeWhen
403FORBIDDENThe user's role ranks above yours, the new role does, or you tried to change your own role or deactivate yourself.
404NOT_FOUNDNo such user.
409CUSTOMER_ACCOUNTIt is a hosting customer. Manage it under Hosting.
409LAST_OWNERThe change would leave the panel without an active owner.
422VALIDATION_ERRORNo fields, or an invalid one.
POST/api/v1/users/:id/password-reset
Auth
Session cookie (+ CSRF token) or API token
Permission
users.manage
Token scope
full

Makes a one-time reset link for a user, valid for 2 hours, and emails it when panel email is set up. Use it when someone forgot their password and the panel cannot send email.

Example request

curl -X POST https://panel.example.com/api/v1/users/7b1e4d2a-9c3f-4e8b-a5d6-0f2c8e1b3a94/password-reset \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { resetUrl, expiresAt } = await panel.request('POST', `/users/${userId}/password-reset`);

Response 200 OK

{
  "success": true,
  "data": { "resetUrl": "https://panel.example.com/reset-password#token=…", "expiresAt": "2026-11-10T11:30:00.000Z", "email": null },
  "message": "Reset link created. Send them the link.",
  "requestId": "…"
}

Errors

StatusCodeWhen
403FORBIDDENThe user's role ranks above yours.
404NOT_FOUNDNo such user.

Reset two-factor sign-in

POST/api/v1/users/:id/2fa/reset
Auth
Session cookie (+ CSRF token) or API token
Permission
users.manage
Token scope
full

For someone who lost their authenticator and their recovery codes. Turns two-factor sign-in off for the user, deletes their recovery codes and signs them out everywhere. They sign in with their password alone and can set it up again.

Example request

curl -X POST https://panel.example.com/api/v1/users/7b1e4d2a-9c3f-4e8b-a5d6-0f2c8e1b3a94/2fa/reset \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const user = await panel.request('POST', `/users/${userId}/2fa/reset`);

Response 200 OK with the user object, twoFactorEnabled: false.

Errors

StatusCodeWhen
400BAD_REQUESTIt is your own account. Turn it off on your account page instead.
403FORBIDDENThe user's role ranks above yours.
404NOT_FOUNDNo such user.
409TWO_FACTOR_OFFTwo-factor sign-in is already off for this user.

List roles

GET/api/v1/roles
Auth
Session cookie (+ CSRF token) or API token
Permission
roles.read
Token scope
read

Every role with its permissions and how many users have it, plus the description of every permission.

Example request

curl https://panel.example.com/api/v1/roles \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { roles, permissions } = await panel.users.roles();

Response 200 OK

{
  "success": true,
  "data": {
    "roles": [
      {
        "name": "viewer",
        "description": "Read-only access to servers, websites, DNS zones, email, apps, containers, databases, backups, cron jobs and jobs, and the AI assistant",
        "rank": 10,
        "isSystem": true,
        "userCount": 3,
        "permissions": ["alerts.read", "applications.read", "assistant.use", "backups.read", "containers.read", "cron.read", "dashboard.view", "databases.read", "dns.read", "jobs.read", "mail.read", "servers.read", "websites.read"]
      }
    ],
    "permissions": [
      { "key": "dashboard.view", "description": "View the dashboard" },
      { "key": "users.read", "description": "View users and their roles" }
    ]
  },
  "message": "OK",
  "requestId": "…"
}

Roles are listed by rank, highest first.

List audit log entries

GET/api/v1/audit-logs
Auth
Session cookie (+ CSRF token) or API token
Permission
audit.read
Token scope
logs

The audit log, newest first. Every change, sign-in, permission denial and API token call is recorded with who did it, from where and with which request id. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
actionstringNoAn action or its prefix: website. matches website.create, website.delete and so on.
actorIdstringNoThe id of the user (or other actor) who acted.
targetTypestringNoSuch as website, server or user.
targetIdstringNoThe id of the record acted on.
resultstringNosuccess, failure or denied.
from, tostringNoISO 8601 date-times bounding occurredAt.
sortstringNooccurredAt (default) or action.

Example request

curl "https://panel.example.com/api/v1/audit-logs?action=auth.&result=failure&from=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.auditLog.list({ action: 'auth.', result: 'failure', from: '2026-11-01T00:00:00Z' });

Response 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 18342,
        "occurredAt": "2026-11-10T08:41:09.000Z",
        "actor": { "type": "anonymous", "id": null, "label": "ada@example.com" },
        "action": "auth.login",
        "target": { "type": "user", "id": "3c9f0a52-7d1e-4b8a-9f3e-2a6d5c4b1e07", "label": "ada@example.com" },
        "result": "failure",
        "ip": "198.51.100.24",
        "userAgent": "Mozilla/5.0 …",
        "requestId": "6f1c2a4e-1b7d-4c55-9a0e-3d2f8b7c9e10",
        "metadata": { "reason": "bad_password" }
      }
    ],
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
  },
  "message": "OK",
  "requestId": "…"
}

target is null for actions without one. metadata holds details that depend on the action; passwords, environment values and file contents never appear in it. See Audit log.