# API Key

签发、列出、吊销和轮换用于认证请求的 API Key。

API 参考。Base URL：`https://api.mirabase.dev`

## 列出 API Key

`GET /v2/api-keys`

本租户的 Key，不含密钥，按 id 排序。需要 `tenant_admin`，且 Key 不受 Space 限制。不需要任何能力。

**需要的能力** 不检查能力。

指南：[认证与 API Key](https://mirabase.io/zh/developers/authentication.md#rotate)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevApiKey[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/api-keys" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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

## 创建 API Key

`POST /v2/api-keys`

签发 API Key。只有 `tenant_admin` 可以签发，Agent 不能为自己签发。一个账户最多持有 `tenant_api_keys` 个活跃的 Key（见 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits)），超出时返回 409 `tenant_limit_reached`。在有团队的账户中，Admin 的权限取决于归属关系：不能对 Owner 或其他 Admin 执行这些操作；对其他成员只能修改能力或吊销 Key，不能签发或轮换 Key；只能管理自己创建的 Agent 和最终用户。其他操作返回 403 `forbidden`；已移除的成员不能执行任何此类操作。不需要任何能力。

**需要的能力** 不检查能力。

指南：[认证与 API Key](https://mirabase.io/zh/developers/authentication.md#api)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevCreateApiKeyRequest` 字段名为 `actor_id` 和 `grant_capabilities`，而非 `principal_id` 和 `capabilities`：后两个名字由服务端控制，请求里出现就会被 `identity_override` 拒绝。`POST` 和 `PATCH /v2/principals` 同样如此。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `actor_id` | `DevId` | 必填 | 这个 Key 代表的主体。比自身主体更窄的调用方 Key（能力更少、限定了 Space 或元数据范围）只能为该主体签发 Key。 |
| `name` | `string` | 必填 | Key 的名称，1 到 256 个字符，用于在列表中区分各个 Key。 长度 1 到 256 |
| `grant_capabilities` | `DevCapability[]` | 必填 | 不能超过该主体和调用方的能力。 至少 1 项 |
| `allowed_space_ids` | `DevId[]` | 可选 | 不传表示不限制 Space；不接受空数组。 1 到 100 项 |
| `metadata_scope` | `DevMetadataScope` | 可选 | 将 Key 限制在带有这些元数据标签的 Entry 上：1 到 8 个键，每个键 1 到 8 个值。创建后不可修改，轮换 Key 时保持不变。带范围的 Key 可调用 `whoami`、`limits`、读取 Space、[`GET /v2/entries`](https://mirabase.io/zh/developers/api/entries.md#entries-list)、读取 Entry 内容与处理状态、[`GET /v2/jobs/{id}`](https://mirabase.io/zh/developers/api/jobs.md#jobs-read)、读取记忆、`search`、`context`、`answer`、上下文反馈、`ingest` 和 MCP；其他操作均返回 403 `scoped_key_route_unavailable`。导入时在受限键上传入范围外的值返回 403 `outside_metadata_scope`。若要在最终用户之间实现硬隔离，请为每个用户创建一个 Space；范围用于在同一 Space 内做更细的划分。 |
| `expires_at` | `string (date-time)` | 可选 | 必须是未来时间。调用方的 Key 有到期时间时必填，且不能晚于该到期时间。 |

### 响应

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

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```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"]}'
```

### 响应结构示例

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

## 读取 API Key

`GET /v2/api-keys/{key_id}`

读取一个 Key 的记录，不含密钥：令牌只在签发或轮换时返回一次。需要 `tenant_admin`，且 Key 不受 Space 限制。本租户没有的 id 返回 404 `not_found`。不需要任何能力。

**需要的能力** 不检查能力。

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `key_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |

### 响应

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

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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

## 吊销 API Key

`DELETE /v2/api-keys/{key_id}`

吊销 Key。此后用它发起的请求返回 401。重复吊销已吊销的 Key 会原样返回。`tenant_admin` 的 Key 始终可以吊销自身，受 Space 限制时也是如此。在有团队的账户中，Admin 的权限取决于归属关系：不能对 Owner 或其他 Admin 执行这些操作；对其他成员只能修改能力或吊销 Key，不能签发或轮换 Key；只能管理自己创建的 Agent 和最终用户。其他操作返回 403 `forbidden`；已移除的成员不能执行任何此类操作。需要 `tenant_admin` 角色，不需要任何能力。

**需要的能力** 不检查能力。

指南：[认证与 API Key](https://mirabase.io/zh/developers/authentication.md#rotate)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `key_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |

### 响应

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

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl -X DELETE "https://api.mirabase.dev/v2/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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

## 轮换 API Key

`POST /v2/api-keys/{key_id}/rotate`

在一个事务中签发一个主体、名称、Space、元数据范围和到期时间都相同的新 Key，并吊销旧 Key；主体此后失去的能力不会带到新 Key 上。轮换已吊销或已过期的 Key 返回 409 `api_key_not_live`。Key 不能轮换自己（返回 409 `self_rotation_not_allowed`）：响应一旦丢失，将没有可用于认证的凭据。要轮换当前 Key，先用 [`POST /v2/api-keys`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-create) 签发新 Key，切换到新 Key，再吊销旧 Key。在有团队的账户中，Admin 的权限取决于归属关系：不能对 Owner 或其他 Admin 执行这些操作；对其他成员只能修改能力或吊销 Key，不能签发或轮换 Key；只能管理自己创建的 Agent 和最终用户。其他操作返回 403 `forbidden`；已移除的成员不能执行任何此类操作。需要 `tenant_admin` 角色，不需要任何能力。

**需要的能力** 不检查能力。

指南：[认证与 API Key](https://mirabase.io/zh/developers/authentication.md#rotate)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `key_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 响应

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

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl -X POST "https://api.mirabase.dev/v2/api-keys/$KEY_ID/rotate" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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