# API keys

Issue, list, revoke, and rotate the keys that authenticate requests.

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

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

### 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` | `DevApiKey[]` | 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/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`](https://mirabase.io/developers/api/usage.md#usage-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](https://mirabase.io/developers/authentication.md#api)

### 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` `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 | Required | Description |
| --- | --- | --- | --- |
| `actor_id` | `DevId` | Required | 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. |
| `name` | `string` | Required | A name for the key, 1 to 256 characters, to tell keys apart in listings. length 1..256 |
| `grant_capabilities` | `DevCapability[]` | Required | Must not exceed the capabilities of the principal or of the caller. min items 1 |
| `allowed_space_ids` | `DevId[]` | Optional | Omit to leave Spaces unrestricted; an empty list is rejected. items 1..100 |
| `metadata_scope` | `DevMetadataScope` | Optional | 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`](https://mirabase.io/developers/api/entries.md#entries-list) and an Entry's content and processing, [`GET /v2/jobs/{id}`](https://mirabase.io/developers/api/jobs.md#jobs-read), 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)` | Optional | Must be in the future. Required when the calling key expires, and must not be later than that key's own expiry. |

### Responses

- `201` `application/json` `DevIssuedApiKey`

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

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

### Responses

- `200` `application/json` `DevApiKey`

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

### Parameters

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

### Responses

- `200` `application/json` `DevApiKey`

### 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 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`](https://mirabase.io/developers/api/api-keys.md#apikeys-create), 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](https://mirabase.io/developers/authentication.md#rotate)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `key_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 |

### Responses

- `200` `application/json` `DevIssuedApiKey`

### 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/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…"
}
```
