Principals
MarkdownThe 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
| 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 | DevPrincipal[] | 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/principals" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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
| 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 DevCreatePrincipalRequest
| Field | Type | Description |
|---|---|---|
kindRequired | DevPrincipalKind | What the principal is: a person or an Agent. |
grant_capabilities | DevCapability[] | Capabilities to grant; they must not exceed yours. Omitted means knowledge:read for an Agent and none for a human. |
Responses
201application/jsonDevPrincipal
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/principals" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind":"human"}'Example response
{
"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
| Name | In | Type | Description |
|---|---|---|---|
principal_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
200application/jsonDevPrincipal
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/principals/$PRINCIPAL_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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
| Name | In | Type | Description |
|---|---|---|---|
principal_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 |
Request body
application/json DevUpdatePrincipalRequest
| Field | Type | Description |
|---|---|---|
grant_capabilitiesRequired | DevCapability[] | Replaces the principal's capabilities. You must hold every capability in this list and every capability the principal has now. |
Responses
200application/jsonDevPrincipal
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 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
{
"id": "<id>",
"kind": "human",
"roles": [
"<roles>"
],
"capabilities": [
"knowledge:read"
],
"created_at": "2026-11-06T00:00:00Z"
}