Skip to content
Developer docs
Docs menu

API keys

Markdown

Issue, 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

NameInTypeDescription
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevApiKey[]The items on this page.
next_cursorDevCursorPass 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
curl "https://api.mirabase.dev/v2/api-keys" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
Idempotency-KeyHeaderDevIdempotencyKeyThe 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.

FieldTypeDescription
actor_idRequiredDevIdThe 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.
nameRequiredstringA name for the key, 1 to 256 characters, to tell keys apart in listings.length 1..256
grant_capabilitiesRequiredDevCapability[]Must not exceed the capabilities of the principal or of the caller.min items 1
allowed_space_idsDevId[]Omit to leave Spaces unrestricted; an empty list is rejected.items 1..100
metadata_scopeDevMetadataScopeLimit 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_atstring (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

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
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

json
{
  "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

NameInTypeDescription
key_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

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
curl "https://api.mirabase.dev/v2/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
key_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

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
curl -X DELETE "https://api.mirabase.dev/v2/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
key_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
Idempotency-KeyHeaderDevIdempotencyKeyThe 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

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
curl -X POST "https://api.mirabase.dev/v2/api-keys/$KEY_ID/rotate" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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…"
}