API Keys API
Reference for the API Keys endpoint group — 3 endpoints.
Generated from the live OpenAPI spec. Re-run _generate_api_reference.py after backend changes.
Authentication#
All endpoints require a Bearer JWT in the Authorization header unless noted otherwise. See Concepts → Tokens and scopes and Reference → OAuth endpoints for how to obtain one.
Endpoints#
GET /api/v1/admin/api-keys#
List Api Keys
List API keys — your own by default; all keys for super_admins.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
all_users |
query | no | boolean |
super_admin only: list every user's keys, not just your own. |
include_revoked |
query | no | boolean |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → object |
422 |
application/json → HTTPValidationError |
POST /api/v1/admin/api-keys#
Create Api Key
Create a personal API key for the calling admin.
The plaintext secret is returned exactly once, in this response. Only a hash is stored — a lost secret means revoke + re-create.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Request body:
Required.
application/json→CreateApiKeyRequest
Responses:
| Status | Body |
|---|---|
201 |
application/json → object |
422 |
application/json → HTTPValidationError |
DELETE /api/v1/admin/api-keys/{key_id}#
Revoke Api Key
Revoke an API key. Owners revoke their own; super_admins any.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
key_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Request body:
application/json→RevokeApiKeyRequest|null
Responses:
| Status | Body |
|---|---|
200 |
application/json → object |
422 |
application/json → HTTPValidationError |
Schemas#
Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.
CreateApiKeyRequest#
| Field | Type | Required | Description |
|---|---|---|---|
name |
string |
yes | |
scopes |
array of string |
yes | Subset of {admin:read, admin:write}. Write implies read. |
expires_in_days |
integer | null |
no | Optional expiry. Omit for a non-expiring key. |
group_id |
string | null |
no | Optional group binding: the key only works while you remain an active member of this group. |
HTTPValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
detail |
array of ValidationError |
no |
RevokeApiKeyRequest#
| Field | Type | Required | Description |
|---|---|---|---|
reason |
string | null |
no |
ValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
loc |
array of string | integer |
yes | |
msg |
string |
yes | |
type |
string |
yes |