Skip to content
Developer docs
Docs menu

Principals

Markdown

The people and Agents of an account, and the capabilities each can hold.

List principals

GET/v2/principals

Principals of this tenant, ordered by id. Requires tenant_admin and a key without Space restrictions. Needs no capability.

Capability No capability is checked.

Guide: Permissions

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
dataRequiredDevPrincipal[]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/principals" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "id": "<id>",
      "kind": "human",
      "roles": [
        "<roles>"
      ],
      "capabilities": [
        "knowledge:read"
      ],
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

Create a principal

POST/v2/principals

Create a principal. An Agent has its own ACL, memory, and audit identity. Requires tenant_admin. An account holds at most tenant_principals of them (GET /v2/limits); one more returns 409 tenant_limit_reached. Needs no capability.

Capability No capability is checked.

Guide: Permissions

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 DevCreatePrincipalRequest

FieldTypeDescription
kindRequiredDevPrincipalKindWhat the principal is: a person or an Agent.
grant_capabilitiesDevCapability[]Capabilities to grant; they must not exceed yours. Omitted means knowledge:read for an Agent and none for a human.

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/principals" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"human"}'

Example response

json
{
  "id": "<id>",
  "kind": "human",
  "roles": [
    "<roles>"
  ],
  "capabilities": [
    "knowledge:read"
  ],
  "created_at": "2026-11-06T00:00:00Z"
}

Read a principal

GET/v2/principals/{principal_id}

Read one principal. 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
principal_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/principals/$PRINCIPAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "id": "<id>",
  "kind": "human",
  "roles": [
    "<roles>"
  ],
  "capabilities": [
    "knowledge:read"
  ],
  "created_at": "2026-11-06T00:00:00Z"
}

Update a principal's capabilities

PATCH/v2/principals/{principal_id}

Replace a principal's capabilities with grant_capabilities: what is not in the list is taken away. A key restricted to Spaces cannot call this. The change is written to the audit log. 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.

Parameters

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

Request body

application/json DevUpdatePrincipalRequest

FieldTypeDescription
grant_capabilitiesRequiredDevCapability[]Replaces the principal's capabilities. You must hold every capability in this list and every capability the principal has now.

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 PATCH "https://api.mirabase.dev/v2/principals/$PRINCIPAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grant_capabilities":["knowledge:read"]}'

Example response

json
{
  "id": "<id>",
  "kind": "human",
  "roles": [
    "<roles>"
  ],
  "capabilities": [
    "knowledge:read"
  ],
  "created_at": "2026-11-06T00:00:00Z"
}