# API keys & access levels

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

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](/docs/sentinel/v2/concepts/security-groups/). 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 level | Send | Example | Where |
| --- | --- | --- | --- |
| `public` | The 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`, `full` | The id and secret with HTTP Basic | `Authorization: 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](/docs/sentinel/v2/security/sign-in/).

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](/docs/sentinel/v2/concepts/security-groups/).

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](/docs/sentinel/v2/policies/api-keys/#set-an-expiry).

## Credential matrix

| Endpoint group | Admin session | `public` key | `restricted` key | `full` key |
| --- | --- | --- | --- | --- |
| **Widget**: `GET`/`POST /v2/challenge`, `GET /v2/challenge/audio/{file}`, `POST /v2/verify` | No | Yes (Bearer or `apiKey`) | No | No |
| **Inspect**: `GET /v2/inspect` | No | Yes (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/signature` | No | No | Yes (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) | No | No | Yes (Basic), with the permissions of its group's `role`; see [Restricted vs full](#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, Doctor | Yes (with the matching permission or root) | No | No | No |
| **Unauthenticated**: `GET /`, `/v2/auth/*` (sign-in), `GET /v2/app-config`, `GET /v2/openapi.json` | Not needed | Not needed | Not needed | Not needed |

The widget and detection endpoints, and `GET /v2/inspect`, form the functional API, which needs an active license. See [Licensing](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/configure/listeners/).

For request and response schemas, see the [API reference](/sentinel-api-docs-v2.html).

### 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](/docs/sentinel/v2/concepts/accounts-users/).
- **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](/docs/sentinel/v2/operations/audit-logs/) 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

| HTTP | Code | When |
| --- | --- | --- |
| 403 | `BEARER_AUTH_PUBLIC_API_KEY` | A `restricted` or `full` key was sent by id (Bearer or `apiKey`). Send it with Basic `id:secret`. |
| 403 | `PUBLIC_API_KEY_REQUIRED` / `NON_PUBLIC_API_KEY_REQUIRED` | The key's access level doesn't fit the endpoint: a server key on a widget endpoint, or a `public` key on a detection endpoint. |
| 403 | `FULL_API_KEY_REQUIRED` | A `public` or `restricted` key called an account-management endpoint. |
| 403 | `PERMISSION_REQUIRED` | A `full` key called an account-management endpoint, but its group has no role or the role doesn't list the feature. |
| 401 | `API_KEY_REQUIRED` | No 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](/docs/sentinel/v2/reference/errors/).

### 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](/docs/sentinel/v2/policies/api-keys/) and [Accounts, users & roles](/docs/sentinel/v2/concepts/accounts-users/).

### 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]`](/docs/sentinel/v2/reference/configuration/#api_key_cache) and [Clustering & high availability](/docs/sentinel/v2/operations/clustering/).

<Callout type="note" title="Changed in v2">

`restricted` keys now need their secret too: like `full` keys, they authenticate only with Basic `id:secret`. Widget endpoints accept only `public` keys, so move widget keys of `restricted` or `full` groups to a `public` group. `POST /v2/verify/signature` takes Basic credentials instead of a `secret` in the body. See [Breaking changes](/docs/sentinel/v2/upgrade/breaking-changes/).

## Key terms

| Term | Meaning |
| --- | --- |
| API key | A credential (`key_…` id plus `sec_…` secret) owned by an account, optionally with an expiry |
| Access level | `public`, `restricted` or `full`; set on the security group, not on the key |
| `public` key | Sent by id only; serves the widget endpoints and `GET /v2/inspect` |
| `restricted` key | Sent with Basic `id:secret` from servers; calls the detection endpoints and `GET /v2/inspect` |
| `full` key | Like 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 session | A 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:

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

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

```bash
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:

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

```json
{
"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:

```bash
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:

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

## Related

- [Security groups & rules](/docs/sentinel/v2/concepts/security-groups/)
- [Managing API keys](/docs/sentinel/v2/policies/api-keys/)
- [Widget integration](/docs/sentinel/v2/integrate/widget/)
- [Verifying submissions](/docs/sentinel/v2/integrate/verification/)
- [Backend APIs](/docs/sentinel/v2/integrate/backend-apis/)
- [Error codes](/docs/sentinel/v2/reference/errors/)
