Skip to main content
ALTCHA®

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.

FieldTypeDescription
namestring1 to 200 characters, trimmed. Shown in the admin UI, the dashboard and the logs.
securityGroupIdstringThe 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.
requestLoggingstringnone (API default), verification or all. See Request logging.
expiresAtstring | nullRFC 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 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.

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.

LevelAdmin UI labelLogged
noneOffNothing
verificationVerificationGET/POST /v2/challenge and POST /v2/verify. With HIS on, the GET redirect isn't logged; the POST is.
allAllEvery 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 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.
  • 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.

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), 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 apiKeyId to POST /v2/request-logs/_stats for metrics, or to POST /v2/request-logs/_search for 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.

  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:

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 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.
[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.

Start typing to search...

↑ ↓ Navigate ↵ Select