secutils-dev/secutils/api-keys

Secutils.dev: API Keys

API keys are opaque bearer tokens (su_ak_ plus 64 hex characters) that authenticate REST calls in place of an ory_kratos_session cookie. They are the canonical authentication mechanism for scripts, CI pipelines, and AI agents. Each key has a name, an optional expiration date, a usage timestamp, and a single one-time-display plaintext token returned only at creation or regeneration.

Guide: <https://secutils.dev/docs/guides/platform/api_keys>. Full reference: <https://secutils.dev/api-docs/openapi.json>.

Endpoints (tag: user)

Important: every API-key-management endpoint above must be authenticated with the `ory_kratos_session` cookie, not with an API key. The server returns 403 Forbidden to an API-key-authenticated request hitting /api/user/api_keys/*. This is deliberate: it prevents a leaked API key from minting new tokens or rotating itself. Authenticate from a browser session through Kratos first.

Create-key payload

{
  "name": "ci-pipeline",
  "expiresAt": 1893456000
}

expiresAt is optional Unix epoch seconds. Omit it to create a non-expiring key.

Response:

{
  "apiKey": {
    "id": "11111111-...",
    "name": "ci-pipeline",
    "expiresAt": 1893456000,
    "createdAt": 1700000000,
    "updatedAt": 1700000000,
    "lastUsedAt": null
  },
  "token": "su_ak_<64-hex>"
}

The token field is the only place the plaintext token is ever shown. Store it in the agent's secret manager immediately. Subsequent GET calls return only the metadata, never the token.

Using a key

Send the token in the Authorization header on every non-management endpoint:

curl -H "Authorization: Bearer su_ak_<token>" \
  https://secutils.dev/api/webhooks/responders

Any 401 indicates either an unknown token or an expired key; the server distinguishes between the two through the WWW-Authenticate header.

Regenerate vs delete

POST .../_regenerate accepts an optional expiresAt field and returns the same shape as POST /api/user/api_keys, but the key's id is preserved. Any consumer using the previous token loses access immediately, so coordinate the rotation with the consumer's deploy.

DELETE removes the key outright; the id is freed and any consumer using the token gets 401.

Caveats

• API keys grant the same scope as the owning user's session: every

data endpoint, no API-key-management endpoints, no admin endpoints. Treat them as a full credential.

• Limits: 30 API keys per user (configurable via

security.max_user_api_keys); name max 128 chars, unique per user.

• lastUsedAt updates on every authenticated request, with a 60-second

coalescing window to avoid contention. A key that shows null for several minutes after first use has not been exercised.

• For ephemeral automation, prefer creating a short-lived API key with

expiresAt = now + 1h over a never-expiring key.

• Bootstrap recipe: sign in through the UI, open the browser devtools,

copy the ory_kratos_session cookie, then call POST /api/user/api_keys from a shell with that cookie. Subsequent agent calls use the returned token directly.

See also

• Human-readable guide: <https://secutils.dev/docs/guides/platform/api_keys>
• Related skill: every other Secutils skill assumes an API key is

already in $SECUTILS_API_KEY.

• OpenAPI: <https://secutils.dev/api-docs/openapi.json>