跳到主要内容
开发者文档
文档目录

签发、列出、吊销和轮换用于认证请求的 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

响应

  • 200 application/json
字段类型说明
data必填DevApiKey[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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),超出时返回 409 tenant_limit_reached。在有团队的账户中,Admin 的权限取决于归属关系:不能对 Owner 或其他 Admin 执行这些操作;对其他成员只能修改能力或吊销 Key,不能签发或轮换 Key;只能管理自己创建的 Agent 和最终用户。其他操作返回 403 forbidden;已移除的成员不能执行任何此类操作。不需要任何能力。

需要的能力 不检查能力。

指南:认证与 API Key

参数

名称位置类型说明
Idempotency-Key请求头DevIdempotencyKeyIdempotency-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必填stringKey 的名称,1 到 256 个字符,用于在列表中区分各个 Key。长度 1 到 256
grant_capabilities必填DevCapability[]不能超过该主体和调用方的能力。至少 1 项
allowed_space_idsDevId[]不传表示不限制 Space;不接受空数组。1 到 100 项
metadata_scopeDevMetadataScope将 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_atstring (date-time)必须是未来时间。调用方的 Key 有到期时间时必填,且不能晚于该到期时间。

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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

参数

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

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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 签发新 Key,切换到新 Key,再吊销旧 Key。在有团队的账户中,Admin 的权限取决于归属关系:不能对 Owner 或其他 Admin 执行这些操作;对其他成员只能修改能力或吊销 Key,不能签发或轮换 Key;只能管理自己创建的 Agent 和最终用户。其他操作返回 403 forbidden;已移除的成员不能执行任何此类操作。需要 tenant_admin 角色,不需要任何能力。

需要的能力 不检查能力。

指南:认证与 API Key

参数

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

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

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