Skip to main content
ALTCHA®

Managing accounts & users

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

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:

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

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:

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

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:

FieldDescription
UsernameSign-in name, up to 200 characters, without :. Unique, including deleted users.
NameDisplay name. Defaults to the username.
Password8 to 256 characters. A user without a password can't sign in with a password.
ActiveInactive users can't sign in.
RootFull access to every account and to the root-only pages.
MembershipsOne role per account. The form starts with every active default account as Member.

With the API, send POST /v2/users:

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:

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

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> with accounts. The list replaces all of the user's memberships, so send every membership the user should keep:

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" }] }'
{
  "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 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:

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"] }'
{
  "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:

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

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:

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.

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:

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). 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) 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:

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 as user.revoke_sessions.

Users log themselves out everywhere from the user menu with Log out everywhere, which calls 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.

Changes that revoke sessions

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

ChangeRevokes sessions
Password set, changed, or removedyes
User deactivatedyes
Root turned on or offyes
User deletedyes
Username, name, or memberships changedno
User reactivatedno
OTP disabled, passkey removedno

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:

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:

{ "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>, which returns 204 No Content:

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:

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>, which returns 204 No Content:

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.

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

Start typing to search...

↑ ↓ Navigate ↵ Select