# Managing accounts & users

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

Create accounts (tenants), give people access to them with roles, and take access away again. Each task shows the admin UI steps first and then the equivalent `/v2` API call. For how accounts, users, memberships, roles, and root fit together, read [Accounts, users & roles](/docs/sentinel/v2/concepts/accounts-users/) first.

Every task on this page needs a **root** user. The **Accounts**, **Users**, and **Roles** pages appear under **Administration** in the sidebar for root users only, and the matching endpoints return `403 ROOT_PRIVILEGES_REQUIRED` to anyone else. `full` API keys can't call them either, so automation uses a root session.

## Before you start

The API examples send a root session token as `Authorization: Bearer <jwt>`. You get one by signing in with `POST /v2/auth/login`, which returns `{ "data": { "jwt": "…" } }` once any second factor is passed. See [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/).

Your license limits how many accounts and users can exist. Without a usable license, the limit is one of each, which the default account and the bootstrap root user already use. Creating more returns:

```json
{
"code": "LICENSE_LIMIT_REACHED",
"data": { "limit": "users", "max": 1 },
"error": "Licensed limit of users reached (1).",
"statusCode": 403
}
```

Only live records count: a deleted account or user frees its slot. Existing accounts and users are never disabled when you hit the limit. See [Plans & Licensing](/docs/sentinel/v2/plans/).

## Create an account

In the admin UI, open **Accounts → Create account**, enter a **Name**, and click **Create**. Two switches control the account:

- **Active**: on by default. API keys of an inactive account are rejected.
- **Default**: new users created without memberships join every active default account as `member`, and so do LDAP and OAuth users on their first sign-in. Several accounts can be default.

You become the account's `admin` member. Names don't have to be unique, so copy the ID from the **ID** column when you need to tell accounts apart.

With the API, send [`POST /v2/accounts`](/sentinel-api-docs-v2.html#tag/accounts/POST/v2/accounts):

```bash
curl -X POST https://sentinel.example.com/v2/accounts \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{ "name": "Acme" }'
```

```json
{
"data": {
"id": "acc_1k7mtgcru00236jf7ng",
"name": "Acme",
"active": true,
"default": false,
"deleted": false,
"createdAt": "2026-11-18T08:48:51.582929+00:00",
"updatedAt": "2026-11-18T08:48:51.582929+00:00",
"deletedAt": null
}
}
```

`active` defaults to `true` and `default` to `false`. Next, create the account's security groups and API keys; see [Managing API keys](/docs/sentinel/v2/policies/api-keys/).

## Create a user

Sentinel has no invitations and sends no email. You create the user with an initial password and give it to them over a channel you trust. The user then changes it from the user menu with **Change password** (`POST /v2/me/password`), which also signs out their other sessions, and sets up a second factor under **Two-factor authentication**.

In the admin UI, open **Users → Create user** and fill in:

| Field | Description |
| --- | --- |
| **Username** | Sign-in name, up to 200 characters, without `:`. Unique, including deleted users. |
| **Name** | Display name. Defaults to the username. |
| **Password** | 8 to 256 characters. A user without a password can't sign in with a password. |
| **Active** | Inactive users can't sign in. |
| **Root** | Full access to every account and to the root-only pages. |
| **Memberships** | One role per account. The form starts with every active default account as **Member**. |

With the API, send [`POST /v2/users`](/sentinel-api-docs-v2.html#tag/users/POST/v2/users):

```bash
curl -X POST https://sentinel.example.com/v2/users \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
--data-binary @- <<EOF
{
"username": "alice",
"name": "Alice",
"password": "${ALICE_INITIAL_PASSWORD}",
"accounts": [{ "accountId": "acc_1k7mtgcru00236jf7ng", "role": "member" }]
}
EOF
```

The response is the user, with each membership resolved to the account and role:

```json
{
"data": {
"id": "usr_…",
"username": "alice",
"name": "Alice",
"active": true,
"root": false,
"deleted": false,
"otpEnabled": false,
"passkeyCount": 0,
"hasPassword": true,
"accounts": [
  {
    "id": "acc_1k7mtgcru00236jf7ng",
    "name": "Acme",
    "role": { "id": "member", "name": "Member", "permissions": ["alerts", "logs", "training_data"], "readonly": false }
  }
],
…
}
}
```

If you leave `accounts` out, the user joins every active default account as `member`. Send `"accounts": []` to create a user with no memberships. A username that's already used, including by a deleted user, returns `409 USERNAME_TAKEN`.

LDAP and OAuth users aren't created here. Sentinel creates them on their first sign-in, without a password and as `member` of the default accounts, with usernames such as `ldap:alice`. They count toward the license's user limit too. You then manage them like any other user. See [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/).

## Assign roles

A membership gives a user one role in one account. Changes take effect on the user's next request. They don't sign the user out.

### Add or change a membership

In the admin UI, open **Users**, double-click the user (or choose **Edit** in the row's actions), and under **Memberships** click **Add membership**. Pick the **Account** and the **Role**, then click **Save**. To change a role, pick another one in the same row. To take away access to an account, remove its row.

With the API, send [`PATCH /v2/users/<id>`](/sentinel-api-docs-v2.html#tag/users) with `accounts`. The list **replaces all** of the user's memberships, so send every membership the user should keep:

```bash
curl -X PATCH https://sentinel.example.com/v2/users/usr_… \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{ "accounts": [{ "accountId": "acc_1k7mtgcru00236jf7ng", "role": "rol_1k7mtgcs90033o52ias" }] }'
```

```json
{
"data": {
"id": "usr_…",
"username": "alice",
…
"accounts": [
  {
    "id": "acc_1k7mtgcru00236jf7ng",
    "name": "Acme",
    "role": {
      "id": "rol_1k7mtgcs90033o52ias",
      "name": "Support",
      "permissions": ["logs", "training_data"],
      "readonly": false
    }
  }
],
…
}
}
```

`role` takes a role **ID**: `admin`, `member`, `readonly`, or a `rol_…` ID, never a role name. An account may appear only once. A deleted account returns `400 ACCOUNT_NOT_FOUND` and a deleted role `400 ROLE_NOT_FOUND`. Inactive accounts and roles are allowed; an inactive role grants nothing until you reactivate it.

### Create a custom role

The built-in roles are `admin`, `member`, and `readonly`; the [concept page](/docs/sentinel/v2/concepts/accounts-users/#features-and-built-in-roles) lists what each one grants. When none fits, open **Roles → Create role** and set:

- **Name**: up to 100 characters, unique among all roles, including deleted ones.
- **Permissions**: the features the role grants (**Alerts**, **API keys**, **Logs**, **Security groups**, **Training data**).
- **Read-only**: members get read access only.
- **Active**: an inactive role grants no permissions to its members.

With the API, send [`POST /v2/roles`](/sentinel-api-docs-v2.html#tag/roles/POST/v2/roles):

```bash
curl -X POST https://sentinel.example.com/v2/roles \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{ "name": "Support", "permissions": ["logs", "training_data"] }'
```

```json
{
"data": {
"id": "rol_1k7mtgcs90033o52ias",
"name": "Support",
"active": true,
"deleted": false,
"permissions": ["logs", "training_data"],
"readonly": false,
"createdAt": "2026-11-18T08:48:51.593658+00:00",
"updatedAt": "2026-11-18T08:48:51.593658+00:00",
"deletedAt": null
}
}
```

Editing a role changes it at once for every membership that uses it, and for every `full` security group that has it. You can't delete a role while any membership or security group uses it, including memberships of deleted users and deleted accounts:

```json
{ "code": "ROLE_IN_USE", "error": "Role is assigned to users or security groups.", "statusCode": 409 }
```

Turn off **Active** instead, or move the memberships to another role first. Giving a security group a role is covered in [Managing API keys](/docs/sentinel/v2/policies/api-keys/).

## Make a user root

Open **Users**, edit the user, turn on **Root**, and click **Save**. With the API, send `PATCH /v2/users/<id>` with `root`:

```bash
curl -X PATCH https://sentinel.example.com/v2/users/usr_… \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{ "root": true }'
```

A root user can do everything in every account, whatever their memberships. Turning **Root** on or off signs the user out everywhere, so they sign in again with the new privileges. Root users also see the pages under **Administration** in the sidebar: **Accounts**, **Users**, **Roles**, **Threat Intelligence**, **Remote Files**, **Audit Logs**, **Snapshots**, **Cluster**, **Doctor**, **License**, and **Releases**.

<Callout type="tip" title="Keep a second root user">

Root users can't deactivate, demote, or delete themselves (see [Self-protection rules](#self-protection-rules)), and only a root user can reset another user's second factor. A second root user, with its own second factor, lets you recover when the first one loses their authenticator.

## Reset a lost second factor

Users can't turn off their own OTP. When someone loses their authenticator app or passkey, a root user removes it and the user sets up a new one.

### Disable OTP

In **Users**, choose **Disable OTP** in the user's row actions, then confirm. The action is available only when the user's **OTP** column shows **Enabled**. With the API, send [`POST /v2/users/<id>/_disable_otp`](/sentinel-api-docs-v2.html#tag/users):

```bash
curl -X POST https://sentinel.example.com/v2/users/usr_…/_disable_otp \
-H 'Authorization: Bearer <jwt>'
```

It returns `204 No Content`, even if OTP wasn't enabled. The user's next sign-in asks only for username and password, unless they have passkeys, which then become the second factor. The user's sessions stay valid. They can set up an authenticator app again under **Two-factor authentication** in the user menu.

### Remove a passkey

In **Users**, choose **Manage passkeys** in the user's row actions and click **Remove** next to the lost passkey. You can remove the user's last second factor too. With the API, list the user's passkeys with `GET /v2/users/<id>/passkeys` and delete one with `DELETE /v2/users/<id>/passkeys/<passkeyId>` ([API reference](/sentinel-api-docs-v2.html#tag/users)). Neither call needs a step-up check.

## Revoke sessions

A session token stays valid until it expires (`[auth] jwt_ttl`, default `24h`; see the [configuration reference](/docs/sentinel/v2/reference/configuration/#auth)) or until Sentinel revokes all of the user's sessions. After that, the user's old session tokens and step-up tokens get `401 UNAUTHORIZED`, and the user can sign in again at once.

### Log a user out everywhere

To end every session of a user without changing anything else, for example after a laptop is lost, choose **Log out everywhere** in the user's row actions in **Users**, then confirm. The action is unavailable for deleted users. With the API, a root user sends [`POST /v2/users/<id>/_revoke_sessions`](/sentinel-api-docs-v2.html#tag/users):

```bash
curl -X POST https://sentinel.example.com/v2/users/usr_…/_revoke_sessions \
-H 'Authorization: Bearer <jwt>'
```

It returns `204 No Content`. An unknown or deleted user returns `404 NOT_FOUND`, and a caller who isn't root gets `403 ROOT_PRIVILEGES_REQUIRED`. Used on your own id, it ends your current session too. The action is recorded in the [audit log](/docs/sentinel/v2/operations/audit-logs/) as `user.revoke_sessions`.

Users log themselves out everywhere from the user menu with **Log out everywhere**, which calls [`POST /v2/me/_revoke_sessions`](/sentinel-api-docs-v2.html#tag/me/POST/v2/me/_revoke_sessions). It ends every session of the caller, the current one included, and clears the browser's cookie. See [Logging out](/docs/sentinel/v2/security/sign-in/#logging-out).

### Changes that revoke sessions

Besides **Log out everywhere**, these changes revoke every session of the user:

| Change | Revokes sessions |
| --- | --- |
| Password set, changed, or removed | yes |
| User deactivated | yes |
| **Root** turned on or off | yes |
| User deleted | yes |
| Username, name, or memberships changed | no |
| User reactivated | no |
| OTP disabled, passkey removed | no |

For a user who signs in through LDAP or OAuth, **Log out everywhere** ends their sessions without touching how they sign in. Sending `"password": null`, or **Remove password** in the UI, also logs the user out but leaves them unable to sign in with a password.

Changing your own password in **Users** signs you out too. **Log out** (`POST /v2/auth/logout`) only clears the browser's cookie; the token itself stays valid until it expires. To end your sessions in every browser and script, use **Log out everywhere**.

## Disable or delete a user

**Disable** a user to block access while keeping the user. Edit the user, turn off **Active**, and click **Save**, or send:

```bash
curl -X PATCH https://sentinel.example.com/v2/users/usr_… \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{ "active": false }'
```

The user's sessions end, and signing in returns:

```json
{ "code": "USER_DISABLED", "error": "User is disabled.", "statusCode": 403 }
```

Send `"active": true` to reactivate the user. They have to sign in again.

**Delete** a user who should never come back. Choose **Delete** in the row's actions, or select several users and click **Delete**. With the API, send [`DELETE /v2/users/<id>`](/sentinel-api-docs-v2.html#tag/users), which returns `204 No Content`:

```bash
curl -X DELETE https://sentinel.example.com/v2/users/usr_… \
-H 'Authorization: Bearer <jwt>'
```

Deleting ends the user's sessions. It's a soft delete: `GET /v2/users/<id>` still returns the user with `"deleted": true`, the username can't be used again, and the user's memberships stay in the database, so their roles count as in use.

## Disable or delete an account

**Disable** an account to stop its traffic for a while, for example for an unpaid tenant. Edit the account, turn off **Active**, and click **Save**, or send:

```bash
curl -X PATCH https://sentinel.example.com/v2/accounts/acc_… \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{ "active": false }'
```

From then on, every API key of the account is refused with `403 ACCOUNT_SUSPENDED`, including widget keys, so widgets on your sites stop getting challenges. Members keep their memberships and still see the account. Send `"active": true` to turn the keys back on.

**Delete** an account you no longer need. Choose **Delete** in the row's actions, or send [`DELETE /v2/accounts/<id>`](/sentinel-api-docs-v2.html#tag/accounts), which returns `204 No Content`:

```bash
curl -X DELETE https://sentinel.example.com/v2/accounts/acc_… \
-H 'Authorization: Bearer <jwt>'
```

After that:

- every API key of the account is refused with `403 ACCOUNT_DELETED`,
- the account disappears from its members' account lists, and new memberships can't name it (`400 ACCOUNT_NOT_FOUND`),
- members lose access to it: their memberships stay in the database (so their roles still count as in use) but grant nothing, and the account's request logs, security groups, API keys, and training data return `403 PERMISSION_REQUIRED` or `404 NOT_FOUND` to non-root users,
- its security groups and API keys are kept but can't be used again,
- it no longer counts toward the license's account limit.

<Callout type="danger" title="Deleting can't be undone">

Deleted accounts, users, and roles can't be restored, and their usernames and role names can't be reused. To stop access for a while, deactivate the account or user instead.

## Self-protection rules

Sentinel stops root users from locking themselves out. When the target is the caller, these return `400 CANNOT_MODIFY_SELF`:

- turning off your own **Active** (`"active": false`),
- turning off your own **Root** (`"root": false`),
- deleting yourself.

```json
{ "code": "CANNOT_MODIFY_SELF", "error": "Cannot disable or demote yourself.", "statusCode": 400 }
```

The admin UI shows "You can't deactivate or demote yourself." on your own user. Another root user has to make these changes, so a root user can only be demoted, disabled, or deleted while another root user exists.

The other error codes these endpoints return are listed in the [Error codes reference](/docs/sentinel/v2/reference/errors/#management-api).

## Related

- [Accounts, users & roles](/docs/sentinel/v2/concepts/accounts-users/)
- [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/)
- [Managing API keys](/docs/sentinel/v2/policies/api-keys/)
- [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/)
- [Plans & Licensing](/docs/sentinel/v2/plans/)
- [Error codes reference](/docs/sentinel/v2/reference/errors/#management-api)
- API reference: [accounts](/sentinel-api-docs-v2.html#tag/accounts), [users](/sentinel-api-docs-v2.html#tag/users), and [roles](/sentinel-api-docs-v2.html#tag/roles)
