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.
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.
| Role | Rank | What it is for |
|---|---|---|
owner | 40 | Full control of the panel, including other owners and the server terminal |
admin | 30 | Manage servers, users (except owners) and settings |
developer | 20 | View 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 |
viewer | 10 | Read-only access, and the AI assistant |
customer | 5 | A 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
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/users | List users |
| POST | /api/v1/users | Invite a user |
| GET | /api/v1/users/:id | Get a user |
| PATCH | /api/v1/users/:id | Update a user |
| POST | /api/v1/users/:id/password-reset | Issue a password reset link |
| POST | /api/v1/users/:id/2fa/reset | Reset two-factor sign-in |
| GET | /api/v1/roles | List roles |
| GET | /api/v1/audit-logs | List 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
/api/v1/usersStaff accounts, newest first. Supports the list parameters.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Matches email or name. |
status | string | No | active or inactive. |
role | string | No | owner, admin, developer, viewer or customer. Without it, customers are left out. |
sort | string | No | createdAt (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
/api/v1/usersCreates 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
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Must not belong to another user. |
name | string | Yes | 1 to 120 characters. |
role | string | Yes | owner, 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
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | You lack users.manage, the role ranks above yours, or the role is customer. |
| 409 | CONFLICT | A user with this email already exists. |
| 422 | VALIDATION_ERROR | A field is invalid. |
Get a user
/api/v1/users/:idExample 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such user. |
Update a user
/api/v1/users/:idRenames 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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | 1 to 120 characters. |
role | string | No | owner, admin, developer or viewer, at or below your own role. |
isActive | boolean | No | false 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
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | The user's role ranks above yours, the new role does, or you tried to change your own role or deactivate yourself. |
| 404 | NOT_FOUND | No such user. |
| 409 | CUSTOMER_ACCOUNT | It is a hosting customer. Manage it under Hosting. |
| 409 | LAST_OWNER | The change would leave the panel without an active owner. |
| 422 | VALIDATION_ERROR | No fields, or an invalid one. |
Issue a password reset link
/api/v1/users/:id/password-resetMakes 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
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | The user's role ranks above yours. |
| 404 | NOT_FOUND | No such user. |
Reset two-factor sign-in
/api/v1/users/:id/2fa/resetFor 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
| Status | Code | When |
|---|---|---|
| 400 | BAD_REQUEST | It is your own account. Turn it off on your account page instead. |
| 403 | FORBIDDEN | The user's role ranks above yours. |
| 404 | NOT_FOUND | No such user. |
| 409 | TWO_FACTOR_OFF | Two-factor sign-in is already off for this user. |
List roles
/api/v1/rolesEvery 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
/api/v1/audit-logsThe 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
| Name | Type | Required | Description |
|---|---|---|---|
action | string | No | An action or its prefix: website. matches website.create, website.delete and so on. |
actorId | string | No | The id of the user (or other actor) who acted. |
targetType | string | No | Such as website, server or user. |
targetId | string | No | The id of the record acted on. |
result | string | No | success, failure or denied. |
from, to | string | No | ISO 8601 date-times bounding occurredAt. |
sort | string | No | occurredAt (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.
API tokens
Create, list and revoke VaultPanel API tokens, and the scopes that decide which permissions a token carries on behalf of its owner.
Panel settings
API reference for the panel's own settings - putting the panel on a domain, its address, and the email it sends for invites, password resets and alerts.