Skip to main content
ALTCHA®

Accounts, users & roles

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.

Features and built-in roles

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

FeatureEndpointsadminmemberreadonly
alertsAlerts of the accountread & writeread & writeread
api_keys/v2/api-keys*read & write——
logs/v2/request-logs*read & writeread & writeread
security_groups/v2/security-groups*read & write——
training_data/v2/training-data*, /v2/training-suggestions*read & writeread & writeread

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.

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

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.

Key terms

TermMeaning
AccountTenant that owns API keys, security groups, and training data
UserAdmin identity that signs in
RootUser flag that grants full access to every account and the root-only endpoints
MembershipA user's link to one account, with one role
RoleGlobal, named set of features; optionally read-only. Assigned to memberships, and by root to full security groups
FeatureOne 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:

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

Start typing to search...

↑ ↓ Navigate ↵ Select