API keys
MarkdownIssue, list, revoke, and rotate the keys that authenticate requests.
List keys
GET/v2/api-keys
Keys of this tenant, without their secrets, ordered by id. Requires tenant_admin and a key without Space restrictions. Needs no capability.
Capability No capability is checked.
Guide: Authentication and API keys
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | Query | DevCursor | The next_cursor of the previous page. Omit it to start from the first page.length 1..1024 |
limit | Query | integer | How many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20 |
Responses
200application/json
| Field | Type | Description |
|---|---|---|
dataRequired | DevApiKey[] | The items on this page. |
next_cursor | DevCursor | Pass it as cursor to get the next page. Absent on the last page. |
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/api-keys" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"data": [
{
"id": "<id>",
"principal_id": "<principal_id>",
"name": "research",
"prefix": "<prefix>",
"capabilities": [
"knowledge:read"
],
"created_by": "<created_by>",
"created_at": "2026-11-06T00:00:00Z"
}
]
}Create a key
POST/v2/api-keys
Issue an API key. Only a tenant_admin can issue keys; an Agent cannot issue its own. An account holds at most tenant_api_keys live keys (GET /v2/limits); one more returns 409 tenant_limit_reached. In an account with a team, an Admin acts by ownership: never on the Owner or another Admin; on another member, only to change capabilities or revoke keys, not to issue or rotate them; and only on the Agents and end users the Admin created. Anything else returns 403 forbidden, and a removed member can do none of this. Needs no capability.
Capability No capability is checked.
Guide: Authentication and API keys
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | Header | DevIdempotencyKey | The same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512 |
Request body
application/json DevCreateApiKeyRequest Uses actor_id and grant_capabilities instead of principal_id and capabilities, which are server-controlled: a request that sends them is rejected with identity_override. The same applies to POST and PATCH /v2/principals.
| Field | Type | Description |
|---|---|---|
actor_idRequired | DevId | The principal the key acts as. A calling key narrower than its own principal (fewer capabilities, a Space list, or a metadata scope) can issue keys only for that principal. |
nameRequired | string | A name for the key, 1 to 256 characters, to tell keys apart in listings.length 1..256 |
grant_capabilitiesRequired | DevCapability[] | Must not exceed the capabilities of the principal or of the caller.min items 1 |
allowed_space_ids | DevId[] | Omit to leave Spaces unrestricted; an empty list is rejected.items 1..100 |
metadata_scope | DevMetadataScope | Limit the key to Entries that carry these metadata labels: 1 to 8 keys, each with one value or up to 8 values. It cannot be changed afterward, and rotating the key keeps it. A key with a scope can use whoami, limits, reading Spaces, GET /v2/entries and an Entry's content and processing, GET /v2/jobs/{id}, reading memories, search, context, answer, context feedback, ingest, and MCP; every other operation returns 403 scoped_key_route_unavailable. Ingesting with a different value for a metadata key in the scope returns 403 outside_metadata_scope. For a hard boundary between end users, give each user a Space; use a scope for finer slices inside one. |
expires_at | string (date-time) | Must be in the future. Required when the calling key expires, and must not be later than that key's own expiry. |
Responses
201application/jsonDevIssuedApiKey
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/api-keys" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"actor_id":"<actor_id>","name":"research","grant_capabilities":["knowledge:read"]}'Example response
{
"id": "key_01JD2M8C4W",
"principal_id": "prn_01JD2M7ZT6",
"name": "support-bot",
"prefix": "mb_live_7Qx2",
"capabilities": [
"knowledge:read",
"knowledge:write"
],
"created_by": "prn_01JD2M5H0A",
"created_at": "2026-11-17T08:00:00Z",
"token": "mb_live_7Qx2…"
}Read a key
GET/v2/api-keys/{key_id}
Read one key's record, without its secret; the token is returned only once, when the key is issued or rotated. Requires tenant_admin and a key without Space restrictions. An id this tenant does not have returns 404 not_found. Needs no capability.
Capability No capability is checked.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
key_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
200application/jsonDevApiKey
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/api-keys/$KEY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"id": "<id>",
"principal_id": "<principal_id>",
"name": "research",
"prefix": "<prefix>",
"capabilities": [
"knowledge:read"
],
"created_by": "<created_by>",
"created_at": "2026-11-06T00:00:00Z"
}Revoke a key
DELETE/v2/api-keys/{key_id}
Revoke a key. Subsequent requests made with it return 401. Revoking an already revoked key returns it unchanged. A tenant_admin key can always revoke itself, even if it has Space restrictions. In an account with a team, an Admin acts by ownership: never on the Owner or another Admin; on another member, only to change capabilities or revoke keys, not to issue or rotate them; and only on the Agents and end users the Admin created. Anything else returns 403 forbidden, and a removed member can do none of this. Needs the tenant_admin role and no capability.
Capability No capability is checked.
Guide: Authentication and API keys
Parameters
| Name | In | Type | Description |
|---|---|---|---|
key_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
200application/jsonDevApiKey
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X DELETE "https://api.mirabase.dev/v2/api-keys/$KEY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"id": "<id>",
"principal_id": "<principal_id>",
"name": "research",
"prefix": "<prefix>",
"capabilities": [
"knowledge:read"
],
"created_by": "<created_by>",
"created_at": "2026-11-06T00:00:00Z"
}Rotate a key
POST/v2/api-keys/{key_id}/rotate
Issue a replacement with the same principal, name, Spaces, metadata scope, and expiry, and revoke the old key in one transaction; capabilities the principal has lost since are left out. Rotating a revoked or expired key returns 409 api_key_not_live. A key cannot rotate itself (409 self_rotation_not_allowed): a lost response would leave nothing to authenticate with. Instead, issue a new key with POST /v2/api-keys, switch to it, and then revoke the old one. In an account with a team, an Admin acts by ownership: never on the Owner or another Admin; on another member, only to change capabilities or revoke keys, not to issue or rotate them; and only on the Agents and end users the Admin created. Anything else returns 403 forbidden, and a removed member can do none of this. Needs the tenant_admin role and no capability.
Capability No capability is checked.
Guide: Authentication and API keys
Parameters
| Name | In | Type | Description |
|---|---|---|---|
key_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Idempotency-Key | Header | DevIdempotencyKey | The same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512 |
Responses
200application/jsonDevIssuedApiKey
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/api-keys/$KEY_ID/rotate" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"id": "key_01JD2M8C4W",
"principal_id": "prn_01JD2M7ZT6",
"name": "support-bot",
"prefix": "mb_live_7Qx2",
"capabilities": [
"knowledge:read",
"knowledge:write"
],
"created_by": "prn_01JD2M5H0A",
"created_at": "2026-11-17T08:00:00Z",
"token": "mb_live_7Qx2…"
}