# Managing API keys

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

Create an API key for each integration and assign it to a security group, which sets its access level. For the credential model, see [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/).

**Prerequisites:** a security group in the key's account (see [Security groups & rules](/docs/sentinel/v2/concepts/security-groups/)), and a session as root or as a user whose role grants write access to the `api_keys` feature in that account.

## Key settings

A key has four settings. Sentinel generates the id (`key_…`) and the secret (`sec_…`), and you can't choose or change either.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | 1 to 200 characters, trimmed. Shown in the admin UI, the dashboard and the logs. |
| `securityGroupId` | string | The group whose `access` and rules govern the key. The key belongs to the group's account and can only move to another group of the same account. |
| `requestLogging` | string | `none` (API default), `verification` or `all`. See [Request logging](#request-logging). |
| `expiresAt` | string \| null | RFC 3339 time from which the key is refused, or `null` (default) for no expiry. See [Set an expiry](#set-an-expiry). |

Keys have no enabled switch. To stop a key at once, [delete it](#delete-a-key); to stop it at a set time, give it an expiry. For the full schema, see the [API reference](/sentinel-api-docs-v2.html#tag/api-keys/POST/v2/api-keys).

## Choose a security group

The key has no access level of its own: it takes the `access` of its group.

- Use a `public` group for widget keys. The key id is embedded in your pages, so lock the group to your site with rules.
- Use a `restricted` group for servers that call the detection APIs.
- Use a `full` group only for keys that also manage Sentinel, and only with a [role](#give-a-full-key-management-access).

Moving a key to a group with another access level changes how clients must send it, so existing clients may start getting `403` errors. See [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/) for which credential each endpoint accepts.

## Create a key

In the admin UI, open **API Keys → Create API key**, enter a **Name**, pick a **Security group** and a **Request logging** level, optionally set **Expires**, and save. The form shows how a key of the selected group must be sent. Copy the secret from the key's row with **Copy secret** when you need it.

With the API:

```bash
curl https://sentinel.example.com/v2/api-keys \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{"securityGroupId": "sgr_…", "name": "Signup form", "requestLogging": "verification"}'
```

```json
{
"data": {
"id": "key_…",
"accountId": "acc_…",
"securityGroupId": "sgr_…",
"name": "Signup form",
"secret": "sec_…",
"requestLogging": "verification",
"expiresAt": null,
"deleted": false,
"createdAt": "2026-11-18T08:47:31.052349+00:00",
"updatedAt": "2026-11-18T08:47:31.052349+00:00",
"deletedAt": null
}
}
```

An unknown group, or a group of an account you can't write to, returns `400 SECURITY_GROUP_NOT_FOUND`. Without a usable license, an installation can hold one API key; deleted keys don't count. The next key returns:

```json
{
"code": "LICENSE_LIMIT_REACHED",
"data": { "limit": "api_keys", "max": 1 },
"error": "Licensed limit of api_keys reached (1).",
"statusCode": 403
}
```

See [Plans & Licensing](/docs/sentinel/v2/plans/).

## Who can see the secret

Only callers with write access to `api_keys` in the key's account (and root) get the secret; everyone else gets `"secret": null`. See [Who can see secrets](/docs/sentinel/v2/concepts/api-keys/#who-can-see-secrets).

## Request logging

`requestLogging` decides which of the key's requests Sentinel writes to the request logs. The dashboard and its metrics are built only from logged requests.

| Level | Admin UI label | Logged |
| --- | --- | --- |
| `none` | **Off** | Nothing |
| `verification` | **Verification** | `GET`/`POST /v2/challenge` and `POST /v2/verify`. With HIS on, the `GET` redirect isn't logged; the `POST` is. |
| `all` | **All** | Every request authenticated with the key, including `GET /v2/inspect`, the detection endpoints and, for a `full` key, management calls |

Use `verification` for widget keys: the dashboard reports challenges and verifications. Use `all` on a server key when you want its detection calls in the logs too.

The admin UI starts a key of a `public` group at **Verification**, and keys of `restricted` and `full` groups at **Off**, the API default. It warns when logging is off, because the dashboard then shows no data for the key. To change the level of an existing key:

```bash
curl -X PATCH https://sentinel.example.com/v2/api-keys/key_… \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{"requestLogging": "all"}'
```

The change applies to the key's next request; records already logged stay. Retention is set in [`[request_logs]`](/docs/sentinel/v2/reference/configuration/#request_logs). See [Request logs & analytics](/docs/sentinel/v2/operations/request-logs/).

## Set an expiry

A key with an expiry works until its `expiresAt`. From then on, every request with the key gets `403 API_KEY_EXPIRED`:

```json
{
"code": "API_KEY_EXPIRED",
"error": "API key has expired.",
"statusCode": 403
}
```

In the admin UI, set **Expires** in the key's create or edit form, in your browser's time zone. The buttons below the field set it to 1 week, 1 month (30 days), 3 months (90 days) or 1 year (365 days) from now; leave the field empty for no expiry. The **Expires** column of **API Keys** shows **Never** or the time, with an **Expired** badge once it has passed, and can be sorted.

With the API, send `expiresAt` as an RFC 3339 time when you create or change the key:

```bash
curl -X PATCH https://sentinel.example.com/v2/api-keys/key_… \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{"expiresAt": "2027-01-01T00:00:00Z"}'
```

- **The time must be in the future.** A past or unparsable time returns `400 VALIDATION_ERROR` (`expiresAt must be in the future`). Responses return `expiresAt` in UTC with milliseconds, such as `2027-01-01T00:00:00.000Z`.
- **`null` removes the expiry.** `PATCH` with `null` or a later time makes an expired key work again on its next request. A `PATCH` without `expiresAt` keeps the expiry, so you can still rename or move an expired key.
- **Expiry is checked on every request** on every replica, so a key stops at its `expiresAt` without waiting for a [cache reload](#when-changes-apply).
- **An expired key isn't deleted.** It stays in the key list, keeps counting toward the licensed API key limit until you delete it, and the payloads it signed before it expired still pass `POST /v2/verify/signature`. A challenge it issued before it expired can't be verified with `POST /v2/verify` after the expiry.

Sentinel doesn't warn before a key expires. Track upcoming expiries in the **Expires** column, or sort `POST /v2/api-keys/_search` by `expiresAt`.

## Change a key

Use **Edit** on the key's row, or send `PATCH /v2/api-keys/key_…` with only the fields you want to change: `name`, `securityGroupId`, `requestLogging` or `expiresAt`. The response includes the key with its secret. See the [API reference](/sentinel-api-docs-v2.html#tag/api-keys).

## Rotate a secret

Secrets can't be regenerated in place. To rotate, replace the key:

1. Create a new key in the same security group.
2. Give the old key an `expiresAt` after your rollout deadline, so it stops even if nobody remembers to delete it.
3. Deploy the new key to your clients: the new id in your widget pages, or the new `id:secret` pair on your servers.
4. When traffic on the old key stops (check its [usage](#find-a-keys-usage)), delete the old key, which also frees its place in the licensed key limit.

> **Danger:**
>
> Deleting the old key, or its expiry passing, takes effect on its next request: widgets that still embed it can't get challenges, and servers that still send it get `403 API_KEY_INVALIDATED` or `403 API_KEY_EXPIRED`. The secret also signs the key's challenges, so challenges issued under the old key can't be verified once it is deleted or expired; results it signed still pass `POST /v2/verify/signature` after an expiry, but not after deletion. With the one-key baseline limit you must delete the old key before you can create its replacement, which causes an outage for that integration.

## Delete a key

Use **Delete** on the key's row (you can select several), or call the API:

```bash
curl -X DELETE https://sentinel.example.com/v2/api-keys/key_… \
-H 'Authorization: Bearer <jwt>'
```

Sentinel answers `204` with no body. Deletion is a soft delete that can't be undone: the key stays readable with `"deleted": true` and a `deletedAt` time, its later requests get `403 API_KEY_INVALIDATED`, and a second delete returns `404 NOT_FOUND`. See the [API reference](/sentinel-api-docs-v2.html#tag/api-keys).

To list an account's deleted keys, search with `"deleted": true`:

```bash
curl https://sentinel.example.com/v2/api-keys/_search \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{"filter": {"accountId": "acc_…", "deleted": true}}'
```

## Find a key's usage

A key's usage is recorded only while its `requestLogging` is `verification` or `all`.

- In the admin UI, filter the **Dashboard** by the key, or search **Logs** for it.
- With the API, pass `apiKeyId` to `POST /v2/request-logs/_stats` for metrics, or to `POST /v2/request-logs/_search` for raw records:

```bash
curl https://sentinel.example.com/v2/request-logs/_stats \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{"accountId": "acc_…", "apiKeyId": "key_…", "from": "2026-11-17T00:00:00Z", "to": "2026-11-18T00:00:00Z"}'
```

See the [API reference](/sentinel-api-docs-v2.html#tag/request-logs/POST/v2/request-logs/_stats) and [Request logs & analytics](/docs/sentinel/v2/operations/request-logs/). Changes to keys are also recorded in the [audit log](/docs/sentinel/v2/operations/audit-logs/).

## Give a full key management access

A `full` key can call the account-management endpoints (security groups, API keys, logs, alerts and training data) when root gives its security group a role. Only root can do this.

1. As root, open **Security Groups**, then **Edit** on the group (or create a new one).
2. Set **Access** to **Full**, and pick a **Role**, such as **Admin**. The default, **None (no management access)**, gives the keys no management access.
3. Create the key in that group.

With the API, set `access` and `role` together:

```bash
curl -X PATCH https://sentinel.example.com/v2/security-groups/sgr_… \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{"access": "full", "role": "admin"}'
```

A role on a `public` or `restricted` group returns `400 VALIDATION_ERROR` (`role: only full security groups have a role`), and changing `access` away from `full` clears the role. Once a group has a role, only root can create, change or delete it and its keys, and only root sees those keys' secrets; other callers get `403 ROOT_PRIVILEGES_REQUIRED` on writes. See [Restricted vs full](/docs/sentinel/v2/concepts/api-keys/#restricted-vs-full) and the [API reference](/sentinel-api-docs-v2.html#tag/security-groups).

## When changes apply

Every replica keeps API keys, their security groups and their accounts' states in memory (`[api_key_cache]`, on by default):

- The replica that handles your change reloads before it answers, so the change applies to its next request. An expiry takes effect at its `expiresAt` on every replica, as each request checks it.
- It notifies the other replicas over the KV store's pub/sub, so they reload within milliseconds.
- Notices a replica misses, for example while it reconnects to the KV store, are caught up by a background reload every `refresh_interval`.

```toml
[api_key_cache]
enabled          = true   # false: read the key, group and account from the database on every request
refresh_interval = "10s"  # background reload from the database (1s-1h)
```

> **Warning:**
>
> While the database is unreachable, keys keep authenticating with the last loaded data, so a key you deleted shortly before the outage may still work on replicas that didn't reload. See [When the database is down](/docs/sentinel/v2/concepts/api-keys/#when-the-database-is-down).

See [`[api_key_cache]`](/docs/sentinel/v2/reference/configuration/#api_key_cache) and [Clustering & high availability](/docs/sentinel/v2/operations/clustering/).

## Related

- [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/)
- [Security groups & rules](/docs/sentinel/v2/concepts/security-groups/)
- [Accounts, users & roles](/docs/sentinel/v2/concepts/accounts-users/)
- [Request logs & analytics](/docs/sentinel/v2/operations/request-logs/)
- [Error codes](/docs/sentinel/v2/reference/errors/#api-keys-and-security-rules)
- [API reference: API keys](/sentinel-api-docs-v2.html#tag/api-keys)
