Skip to main content
ALTCHA®

API keys & access levels

Sentinel keeps its credentials strictly apart. Admin sessions manage Sentinel, public keys serve the widget, and restricted or full keys call the backend detection APIs from your servers. A full key can also call some management endpoints, but only when root has given its security group a role. This page owns the matrix of which credential each endpoint accepts. Read it before you wire up a widget or a backend, because a key sent to the wrong endpoint, or in the wrong way, is refused.

How it works

Every API key belongs to one account and one security group. The key has no access level of its own: it uses the access of its security group (public, restricted or full). If you move a key to another group, its access level can change, and with it the way you must send it.

Every key has an id (key_…) and a secret (sec_…). How you send them depends on the access level:

Access levelSendExampleWhere
publicThe key id alone, as a Bearer token or in the apiKey query parameter (also apikey, api_key)Authorization: Bearer key_… or ?apiKey=key_…Browsers and apps (the widget)
restricted, fullThe id and secret with HTTP BasicAuthorization: Basic base64("key_…:sec_…")Servers only
  • If an Authorization header is present, Sentinel uses it and ignores the query parameter. Scheme names are case-insensitive. Any scheme other than Bearer or Basic counts as no key.
  • A query-parameter value only counts as a key if it starts with key_.
  • A public key's id is visible to anyone who loads your page, so restrict it with security-group rules, for example to your site's origins. Sentinel still uses the secret of a public key to sign its challenges and verification results.
  • A restricted or full key is refused when only its id is sent. If one leaks into a widget or a URL, the id alone unlocks nothing.

Admin users don't use API keys. They sign in to get a session JWT and send it as Authorization: Bearer <jwt> or in the jwt cookie, which the admin UI sets. See Sign-in methods.

After a key is authenticated, Sentinel evaluates its security group's rules, and they can still deny the request (403 ACCESS_DENIED). See Security groups & rules.

A key works until it's deleted (403 API_KEY_INVALIDATED) or until its optional expiresAt passes (403 API_KEY_EXPIRED). See Set an expiry.

Credential matrix

Endpoint groupAdmin sessionpublic keyrestricted keyfull key
Widget: GET/POST /v2/challenge, GET /v2/challenge/audio/{file}, POST /v2/verifyNoYes (Bearer or apiKey)NoNo
Inspect: GET /v2/inspectNoYes (Bearer or apiKey)Yes (Basic)Yes (Basic)
Detection and lookups: POST /v2/classifier, /v2/eml, /v2/ip, /v2/language, /v2/phishing, /v2/similarity, /v2/threat, /v2/threat/_report, /v2/time-zone, /v2/user-agent, /v2/training-data/_feedback, /v2/verify/signatureNoNoYes (Basic)Yes (Basic)
Account management: /v2/security-groups*, /v2/api-keys*, /v2/request-logs*, POST /v2/alerts/_search, /v2/training-data* (except _feedback), /v2/training-suggestions*Yes (with the matching permission or root)NoNoYes (Basic), with the permissions of its group's role; see Restricted vs full
Other management: /v2/me*, /v2/accounts*, /v2/users*, /v2/roles*, /v2/audit-logs*, /v2/threat-sources*, /v2/threat-entries*, /v2/remote-files*, /v2/snapshots*, /v2/cluster*, licensing, DoctorYes (with the matching permission or root)NoNoNo
Unauthenticated: GET /, /v2/auth/* (sign-in), GET /v2/app-config, GET /v2/openapi.jsonNot neededNot neededNot neededNot needed

The widget and detection endpoints, and GET /v2/inspect, form the functional API, which needs an active license. See Licensing. With [server.public_api], only the widget endpoints (plus GET /v2/inspect and, optionally, POST /v2/verify/signature) are exposed on a separate port. See Listeners.

For request and response schemas, see the API reference.

Restricted vs full

restricted and full keys are sent the same way and call the same detection endpoints. A full key can also call the account-management endpoints in the matrix, but only when its security group has a role:

  • The role sets the permissions. The key gets the permissions of its group's role in the key's own account, checked the same way as a user's membership. The role must be active, it must list the feature (security_groups, api_keys, logs, alerts or training_data), and a read-only role allows reads only. See Accounts, users & roles.
  • No role, no management access. A group without a role, which is the default and the state of every group migrated from v1, gets 403 PERMISSION_REQUIRED on these endpoints.
  • Only root assigns roles. Root sets the role in the security group's Role field, or as role in the security-group API. Only full groups can have one; changing access away from full clears it.
  • A key can't widen its own access. Groups that have a role, and their keys, can be created, changed, or deleted only by root. Everyone else, including the key itself, sees them read-only and never gets their secrets.
  • Rules still apply. The group's rules, rate limits, and API-key alerts apply on management endpoints as they do on detection endpoints.
  • Changes are audited. A change made with a key is recorded in the audit log with the key's id as apiKeyId.

The other management endpoints, such as users, roles, accounts and audit logs, accept only an admin session; an API key gets 401 UNAUTHORIZED there. Use restricted keys for detection-only integrations, and give a full key with a role only to automation that manages Sentinel, such as a CI job that provisions API keys.

Errors you are likely to hit

HTTPCodeWhen
403BEARER_AUTH_PUBLIC_API_KEYA restricted or full key was sent by id (Bearer or apiKey). Send it with Basic id:secret.
403PUBLIC_API_KEY_REQUIRED / NON_PUBLIC_API_KEY_REQUIREDThe key's access level doesn't fit the endpoint: a server key on a widget endpoint, or a public key on a detection endpoint.
403FULL_API_KEY_REQUIREDA public or restricted key called an account-management endpoint.
403PERMISSION_REQUIREDA full key called an account-management endpoint, but its group has no role or the role doesn't list the feature.
401API_KEY_REQUIREDNo key, an unsupported scheme, or a wrong secret. A session JWT sent to a detection endpoint gets this too.

A public key sent with Basic returns 403 BASIC_AUTH_NON_PUBLIC_API_KEY. For every code, see Error codes.

Who can see secrets

Admin users see a key's secret only if they have write access to the api_keys permission of its account (or are root). Read-only callers get secret: null from the API and the admin UI. Keys of a security group that has a role are an exception: only root sees their secrets. Sentinel generates the secret when the key is created. See Managing API keys and Accounts, users & roles.

When the database is down

Sentinel keeps API keys, their security groups and their account states in memory ([api_key_cache], on by default). If the database becomes unreachable, keys keep authenticating with the last loaded data, so challenges and verification keep working, but changes made in the meantime don't take effect. See [api_key_cache] and Clustering & high availability.

Key terms

TermMeaning
API keyA credential (key_… id plus sec_… secret) owned by an account, optionally with an expiry
Access levelpublic, restricted or full; set on the security group, not on the key
public keySent by id only; serves the widget endpoints and GET /v2/inspect
restricted keySent with Basic id:secret from servers; calls the detection endpoints and GET /v2/inspect
full keyLike a restricted key; with a role on its security group, also calls the account-management endpoints
Role (of a security group)Set by root on a full group; the management permissions its keys get in the group's account
Admin sessionA JWT from sign-in; the only credential for users, roles, accounts, audit logs, and the other management endpoints

Examples

A widget requests a challenge with a public key:

curl 'https://sentinel.example.com/v2/challenge?apiKey=key_…'

Your backend parses a User-Agent with a restricted key:

curl https://sentinel.example.com/v2/user-agent \
  -u 'key_…:sec_…' \
  -H 'Content-Type: application/json' \
  -d '{"userAgent": "Mozilla/5.0 …"}'

The same call with the key id only is refused:

curl https://sentinel.example.com/v2/user-agent \
  -H 'Authorization: Bearer key_…' \
  -H 'Content-Type: application/json' \
  -d '{"userAgent": "Mozilla/5.0 …"}'
{
  "code": "BEARER_AUTH_PUBLIC_API_KEY",
  "error": "Restricted and full-access API keys require Basic authentication.",
  "statusCode": 403
}

A provisioning job lists the account's security groups with a full key whose group has the admin role:

curl https://sentinel.example.com/v2/security-groups/_search \
  -u 'key_…:sec_…' \
  -H 'Content-Type: application/json' \
  -d '{"filter": {"accountId": "acc_…"}}'

Without a role on the key's group, the same call is refused:

{
  "code": "PERMISSION_REQUIRED",
  "error": "Permission required for this account.",
  "statusCode": 403
}

Start typing to search...

↑ ↓ Navigate ↵ Select