API Key
Markdown 版签发、列出、吊销和轮换用于认证请求的 API Key。
列出 API Key
GET/v2/api-keys
本租户的 Key,不含密钥,按 id 排序。需要 tenant_admin,且 Key 不受 Space 限制。不需要任何能力。
需要的能力 不检查能力。
指南:认证与 API Key
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
cursor | 查询 | DevCursor | 上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024 |
limit | 查询 | integer | 每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevApiKey[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/api-keys" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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),超出时返回 409 tenant_limit_reached。在有团队的账户中,Admin 的权限取决于归属关系:不能对 Owner 或其他 Admin 执行这些操作;对其他成员只能修改能力或吊销 Key,不能签发或轮换 Key;只能管理自己创建的 Agent 和最终用户。其他操作返回 403 forbidden;已移除的成员不能执行任何此类操作。不需要任何能力。
需要的能力 不检查能力。
指南:认证与 API Key
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
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、读取 Entry 内容与处理状态、GET /v2/jobs/{id}、读取记忆、search、context、answer、上下文反馈、ingest 和 MCP;其他操作均返回 403 scoped_key_route_unavailable。导入时在受限键上传入范围外的值返回 403 outside_metadata_scope。若要在最终用户之间实现硬隔离,请为每个用户创建一个 Space;范围用于在同一 Space 内做更细的划分。 |
expires_at | string (date-time) | 必须是未来时间。调用方的 Key 有到期时间时必填,且不能晚于该到期时间。 |
响应
201application/jsonDevIssuedApiKey
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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"]}'响应结构示例
{
"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。不需要任何能力。
需要的能力 不检查能力。
参数
响应
200application/jsonDevApiKey
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/api-keys/$KEY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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
参数
响应
200application/jsonDevApiKey
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X DELETE "https://api.mirabase.dev/v2/api-keys/$KEY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 签发新 Key,切换到新 Key,再吊销旧 Key。在有团队的账户中,Admin 的权限取决于归属关系:不能对 Owner 或其他 Admin 执行这些操作;对其他成员只能修改能力或吊销 Key,不能签发或轮换 Key;只能管理自己创建的 Agent 和最终用户。其他操作返回 403 forbidden;已移除的成员不能执行任何此类操作。需要 tenant_admin 角色,不需要任何能力。
需要的能力 不检查能力。
指南:认证与 API Key
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
key_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
响应
200application/jsonDevIssuedApiKey
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/api-keys/$KEY_ID/rotate" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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…"
}