# Users and roles

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

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](https://docs.vaultpanel.net/api-reference/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`](https://docs.vaultpanel.net/api-reference/users-and-roles#list-roles) returns each role's exact permissions. See [Users and roles](https://docs.vaultpanel.net/guides/security/users-and-roles) for the full permission list.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/users` | [List users](https://docs.vaultpanel.net/api-reference/users-and-roles#list-users) |
| POST | `/api/v1/users` | [Invite a user](https://docs.vaultpanel.net/api-reference/users-and-roles#invite-a-user) |
| GET | `/api/v1/users/:id` | [Get a user](https://docs.vaultpanel.net/api-reference/users-and-roles#get-a-user) |
| PATCH | `/api/v1/users/:id` | [Update a user](https://docs.vaultpanel.net/api-reference/users-and-roles#update-a-user) |
| POST | `/api/v1/users/:id/password-reset` | [Issue a password reset link](https://docs.vaultpanel.net/api-reference/users-and-roles#issue-a-password-reset-link) |
| POST | `/api/v1/users/:id/2fa/reset` | [Reset two-factor sign-in](https://docs.vaultpanel.net/api-reference/users-and-roles#reset-two-factor-sign-in) |
| GET | `/api/v1/roles` | [List roles](https://docs.vaultpanel.net/api-reference/users-and-roles#list-roles) |
| GET | `/api/v1/audit-logs` | [List audit log entries](https://docs.vaultpanel.net/api-reference/users-and-roles#list-audit-log-entries) |

## The user object

```json
{
  "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` — Permission: users.read — Token scope: read

Staff accounts, newest first. Supports the [list parameters](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

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

```bash
curl "https://panel.example.com/api/v1/users?status=active&role=developer" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items, pagination } = await panel.users.list({ status: 'active', role: 'developer' });
```

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

## Invite a user

`POST /api/v1/users` — 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](https://docs.vaultpanel.net/guides/dns-and-email/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**

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

**JavaScript**

```js
const { user, inviteUrl, email } = await panel.users.invite({
  email: 'grace@example.com',
  name: 'Grace Hopper',
  role: 'developer',
});
```

**Response** `201 Created`

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

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

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/users/7b1e4d2a-9c3f-4e8b-a5d6-0f2c8e1b3a94 \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

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

`PATCH /api/v1/users/:id` — 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**

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

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

**JavaScript**

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

`POST /api/v1/users/:id/password-reset` — 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**

```bash
curl -X POST https://panel.example.com/api/v1/users/7b1e4d2a-9c3f-4e8b-a5d6-0f2c8e1b3a94/password-reset \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { resetUrl, expiresAt } = await panel.request('POST', `/users/${userId}/password-reset`);
```

**Response** `200 OK`

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

`POST /api/v1/users/:id/2fa/reset` — 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**

```bash
curl -X POST https://panel.example.com/api/v1/users/7b1e4d2a-9c3f-4e8b-a5d6-0f2c8e1b3a94/2fa/reset \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

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

`GET /api/v1/roles` — 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**

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

**JavaScript**

```js
const { roles, permissions } = await panel.users.roles();
```

**Response** `200 OK`

```json
{
  "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` — 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](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

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

```bash
curl "https://panel.example.com/api/v1/audit-logs?action=auth.&result=failure&from=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.auditLog.list({ action: 'auth.', result: 'failure', from: '2026-11-01T00:00:00Z' });
```

**Response** `200 OK`

```json
{
  "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](https://docs.vaultpanel.net/guides/security/audit-log).
