# Accounts, users & roles

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

An account is a tenant that owns API keys, security groups, and training data. Users sign in to the admin UI or the `/v2` API and reach accounts through memberships, and each membership's role decides what the user can see and change in that account. You need this model when you give people other than the operator access to Sentinel.

## How it works

- An **account** is a tenant. It owns its API keys, security groups, training data, and request logs. Data never crosses account boundaries.
- A **user** is an admin identity that signs in (password, LDAP, OAuth, or passkey).
- A **membership** links one user to one account with exactly one **role**. A user can be a member of any number of accounts, with a different role in each.
- A **role** is a global, named set of permissions. Each permission is a feature. A role marked read-only grants read access only to its features. An inactive or deleted role grants nothing.
- **Root** is a flag on the user (`root: true`), not a role. A root user passes every permission check in every account, whatever their memberships, and is the only kind of user that can manage accounts, users, roles, threat lists, remote files, the cluster, and snapshots.

When a non-root user calls an account's endpoint, Sentinel checks that the user has a membership in that account and that its role is active and lists the feature. For a write call, the role must not be read-only.

Roles also apply to API keys. Root can give a `full` security group a role, and its keys then get that role's permissions in the group's account, checked the same way. A role used by a membership or a security group can't be deleted (`409 ROLE_IN_USE`); deactivate it instead. See [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/).

### Features and built-in roles

Role permissions name features from a fixed list. On first start, Sentinel creates three built-in roles:

| Feature | Endpoints | `admin` | `member` | `readonly` |
| --- | --- | --- | --- | --- |
| `alerts` | Alerts of the account | read & write | read & write | read |
| `api_keys` | `/v2/api-keys*` | read & write | — | — |
| `logs` | `/v2/request-logs*` | read & write | read & write | read |
| `security_groups` | `/v2/security-groups*` | read & write | — | — |
| `training_data` | `/v2/training-data*`, `/v2/training-suggestions*` | read & write | read & write | read |

Built-in roles are ordinary roles: a root user can edit, deactivate, or delete them, and Sentinel doesn't restore them on restart. Some operations assign them by ID. A user who creates an account becomes its `admin`, and a user created without memberships joins every default account as `member`. Create your own roles in the admin UI under **Roles → Create role**.

Reads are searches, stats, and `GET` of one record. Writes are creates, imports, updates, and deletes. Root-only endpoints have no feature: no role can grant them.

### Bootstrap

On first start with an empty database, Sentinel creates:

- the three built-in roles,
- an account named **Default Account**, marked as default,
- a root user with the username `root`, who is an `admin` member of the default account.

The root password comes from `[bootstrap] root_password` (at least 8 characters). If you leave it unset, Sentinel generates a password and prints it once in the log as a warning. The setting only applies on first start. Changing it later has no effect.

```toml
[bootstrap]
root_password = "${ROOT_PASSWORD}"   # first start only
```

<Callout type="warning" title="Change the generated password">

Anyone who can read the startup log can read a generated root password. Sign in and change it right away, and enable a second factor for root users. See [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/).

The number of accounts and users is limited by your license (one of each without a usable license). Only creation is refused (`403 LICENSE_LIMIT_REACHED`); the default account and the root user are always created. See [Plans & Licensing](/docs/sentinel/v2/plans/).

## Key terms

| Term | Meaning |
| --- | --- |
| Account | Tenant that owns API keys, security groups, and training data |
| User | Admin identity that signs in |
| Root | User flag that grants full access to every account and the root-only endpoints |
| Membership | A user's link to one account, with one role |
| Role | Global, named set of features; optionally read-only. Assigned to memberships, and by root to `full` security groups |
| Feature | One permission: `alerts`, `api_keys`, `logs`, `security_groups`, or `training_data` |

## Examples

**An agency with one account per client.** Create an account per client. Give your staff the `admin` role in every account, and give each client's developer the `member` role in their own account only. Members see request logs and manage training data, but can't create keys or change rules.

**A read-only auditor.** Add the auditor to each account with the `readonly` role. They can search request logs, alerts, and training data. A write call returns `403 READ_ONLY_ROLE`, and a call for a feature the role doesn't list, such as security groups, returns `403 PERMISSION_REQUIRED`:

```json
{ "code": "READ_ONLY_ROLE", "error": "The role grants read access only.", "statusCode": 403 }
```

**A security lead who edits rules but not keys.** Create a role with `security_groups` and `logs`, without `api_keys`. Assign it in the accounts the lead looks after.

The codes a non-root user can hit are listed in the [Error codes reference](/docs/sentinel/v2/reference/errors/#permissions).

## Related

- [Managing accounts & users](/docs/sentinel/v2/policies/accounts-users/)
- [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/)
- [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/)
- [API reference: users](/sentinel-api-docs-v2.html#tag/users) and [roles](/sentinel-api-docs-v2.html#tag/roles)
