# Principals

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

API reference. Base URL: `https://api.mirabase.dev`

## 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](https://mirabase.io/developers/permissions.md#narrowing)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevPrincipal[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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`](https://mirabase.io/developers/api/usage.md#usage-limits)); one more returns 409 `tenant_limit_reached`. Needs no capability.

**Capability** No capability is checked.

Guide: [Permissions](https://mirabase.io/developers/permissions.md#principals)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `kind` | `DevPrincipalKind` | Required | What the principal is: a person or an Agent. |
| `grant_capabilities` | `DevCapability[]` | Optional | Capabilities to grant; they must not exceed yours. Omitted means `knowledge:read` for an Agent and none for a human. |

### Responses

- `201` `application/json` `DevPrincipal`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `principal_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Responses

- `200` `application/json` `DevPrincipal`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `principal_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `grant_capabilities` | `DevCapability[]` | Required | Replaces the principal's capabilities. You must hold every capability in this list and every capability the principal has now. |

### Responses

- `200` `application/json` `DevPrincipal`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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"
}
```
