secutils-api-keys

name

secutils-api-keys

description

Create, list, rename, regenerate, and delete API keys on Secutils.dev. API keys are opaque tokens prefixed `su_ak_` that authenticate programmatic access to every Secutils.dev REST endpoint without a browser session. Trigger when the user asks to "create a Secutils API key", needs to authenticate a script or AI agent against `https://secutils.dev/api/...`, wants to regenerate or rotate an existing key, or needs to manage key expiration. Note that API key management endpoints themselves cannot be invoked with an API key for bootstrap reasons; they require a Kratos session cookie.

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)

Method	Path	Purpose
GET	/api/user/api_keys	List all API keys for the current user (metadata only).
POST	/api/user/api_keys	Create a new key; returns the plaintext token once.
PUT	/api/user/api_keys/{api_key_id}	Rename a key.
DELETE	/api/user/api_keys/{api_key_id}	Delete a key; the token stops working immediately.
POST	/api/user/api_keys/{api_key_id}/_regenerate	Generate a new token for the same name; old token is invalidated.
POST	/api/users/{user_id}/api_keys	(Operator only.) Bootstrap-create a key for another 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