Managing API keys
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.
Prerequisites: a security group in the key's account (see Security groups & rules), 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. |
expiresAt | string | null | RFC 3339 time from which the key is refused, or null (default) for no expiry. See Set an expiry. |
Keys have no enabled switch. To stop a key at once, delete it; to stop it at a set time, give it an expiry. For the full schema, see the API reference.
Choose a security group
The key has no access level of its own: it takes the access of its group.
- Use a
publicgroup for widget keys. The key id is embedded in your pages, so lock the group to your site with rules. - Use a
restrictedgroup for servers that call the detection APIs. - Use a
fullgroup only for keys that also manage Sentinel, and only with a role.
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 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:
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"}'{
"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:
{
"code": "LICENSE_LIMIT_REACHED",
"data": { "limit": "api_keys", "max": 1 },
"error": "Licensed limit of api_keys reached (1).",
"statusCode": 403
}See Plans & Licensing.
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.
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:
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]. See Request logs & analytics.
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:
{
"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:
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 returnexpiresAtin UTC with milliseconds, such as2027-01-01T00:00:00.000Z. nullremoves the expiry.PATCHwithnullor a later time makes an expired key work again on its next request. APATCHwithoutexpiresAtkeeps 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
expiresAtwithout waiting for a cache reload. - 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 withPOST /v2/verifyafter 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.
Rotate a secret
Secrets can't be regenerated in place. To rotate, replace the key:
- Create a new key in the same security group.
- Give the old key an
expiresAtafter your rollout deadline, so it stops even if nobody remembers to delete it. - Deploy the new key to your clients: the new id in your widget pages, or the new
id:secretpair on your servers. - When traffic on the old key stops (check its usage), delete the old key, which also frees its place in the licensed key limit.
Delete a key
Use Delete on the key's row (you can select several), or call the API:
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.
To list an account's deleted keys, search with "deleted": true:
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
apiKeyIdtoPOST /v2/request-logs/_statsfor metrics, or toPOST /v2/request-logs/_searchfor raw records:
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 and Request logs & analytics. Changes to keys are also recorded in the audit log.
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.
- As root, open Security Groups, then Edit on the group (or create a new one).
- Set Access to Full, and pick a Role, such as Admin. The default, None (no management access), gives the keys no management access.
- Create the key in that group.
With the API, set access and role together:
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 and the API reference.
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
expiresAton 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.
[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)See [api_key_cache] and Clustering & high availability.