API keys

6 endpoints at a glance

Method	Path	Summary
GET	/account/api-keys/	List Keys
POST	/account/api-keys/	Create Key
DELETE	/account/api-keys/{key_id}	Revoke Key
GET	/admin/api-keys/	List All Keys
DELETE	/admin/api-keys/{key_id}	Admin Revoke Key
GET	/admin/api-keys/stats/	Get Admin Stats

user_api_keys

---

List Keys

GET

/account/api-keys/

List the calling user's own keys, newest first.

include_revoked=true includes soft-deleted keys; default
hides them. Each row carries the public view (no hash).

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

include_revoked

Type

boolean

Default

false

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/account/api-keys/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

include_revoked

Samples

---

Create Key

POST

/account/api-keys/

Issue a new API key for the calling user.

Returns the persisted doc shape including the plaintext
secret field — surfaced exactly once. The frontend is
expected to show it in a reveal-once dialog and never store it.

Returns 400 on validation failure (empty label, unknown scope,
past-dated expiry, etc.) with a specific detail string the
creation form can echo back to the user.

Parameters

Header Parameters

authorization

x-api-key

Request Body

application/json

{

  

"label": "string",

  

"scopes": [

  

  

"string"

  

],

  

"expires_at_ts": 0

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/account/api-keys/

Playground

Headers

authorization

x-api-key

Body

Samples

---

Revoke Key

DELETE

/account/api-keys/{key_id}

Soft-revoke one of the calling user's keys.

Idempotent — revoking an already-revoked key returns the same
doc unchanged. Returns 404 when the key doesn't exist OR
belongs to a different user (both cases share a response so a
caller can't probe for foreign key ids).

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

key_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

DELETE

/account/api-keys/{key_id}

Playground

Headers

authorization

x-api-key

Variables

Key

Value

key_id*

Samples

---

Get Admin Stats

GET

/admin/api-keys/stats/

Counts blob for the admin dashboard: total, active, revoked,
expired, used-in-last-24h / 7d. Single $facet aggregation
under the hood — one round-trip regardless of branch count.

Parameters

Header Parameters

authorization

x-api-key

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/api-keys/stats/

Playground

Headers

authorization

x-api-key

Samples

---

List All Keys

GET

/admin/api-keys/

Cross-user listing with optional filters.

?username=alice narrows to one user. ?status= is one of
active / revoked / expired (omit for all). Newest-
first, paginated. Each row is the public view (hash stripped).

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

username

status

active = not revoked + not expired; revoked = soft-deleted; expired = past expires_at

limit

Type

integer

Default

50

offset

Type

integer

Default

0

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/api-keys/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

username

status

limit

offset

Samples

---

Admin Revoke Key

DELETE

/admin/api-keys/{key_id}

Revoke any user's key. Used by admins as the ban-hammer for
a leaked secret reported through other channels.

Records revoked_by (the admin's username) on the doc — gives
the audit trail a "who killed this" pointer alongside the
"who created it". Returns 404 when the key id doesn't exist.

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

key_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

DELETE

/admin/api-keys/{key_id}

Playground

Headers

authorization

x-api-key

Variables

Key

Value

key_id*

Samples

---