Skip to content
XOS Developers

apiKeys

Settings module · 6 operations

List API key rows

GET/api-keys

An org-scoped API key with capability scopes and expiry. The secret is shown once and stored hashed. Returns a cursor page of API key rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.

Create an API key

POST/api-keys

Creates an API key with scopes and an expiry, optionally for a service account, through `app.create_api_key`. The full secret is returned once; only its hash is stored. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.

Get an API key

GET/api-keys/{id}

An org-scoped API key with capability scopes and expiry. The secret is shown once and stored hashed. Returns one API key with its `ETag`. A API key the caller may not see returns 404.

Update an API key

PATCH/api-keys/{id}

An org-scoped API key with capability scopes and expiry. The secret is shown once and stored hashed. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.

Revoke an API key

POST/api-keys/{id}/revoke

Revokes the key at once. Requires step-up authentication. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.

Rotate an API key

POST/api-keys/{id}/rotate

Issues a new secret and revokes the old one. The secret is shown once. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.