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

账户中的人和 Agent,以及各自可持有的能力。

列出主体

GET/v2/principals

本租户的主体,按 id 排序。需要 tenant_admin,且 Key 不受 Space 限制。不需要任何能力。

需要的能力 不检查能力。

指南:权限

参数

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

响应

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

错误状态

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

请求示例

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

响应结构示例

json
{
  "data": [
    {
      "id": "<id>",
      "kind": "human",
      "roles": [
        "<roles>"
      ],
      "capabilities": [
        "knowledge:read"
      ],
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

创建主体

POST/v2/principals

创建主体。Agent 有自己的 ACL、记忆和审计身份。需要 tenant_admin。一个账户最多有 tenant_principals 个主体(见 GET /v2/limits),超出返回 409 tenant_limit_reached。不需要任何能力。

需要的能力 不检查能力。

指南:权限

参数

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

请求体

application/json DevCreatePrincipalRequest

字段类型说明
kind必填DevPrincipalKind主体类型:人(human)或 Agent(agent)。
grant_capabilitiesDevCapability[]要授予的能力,不能超过你持有的能力。不传时 Agent 获得 knowledge:read,人没有任何能力。

响应

错误状态

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

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/principals" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"human"}'

响应结构示例

json
{
  "id": "<id>",
  "kind": "human",
  "roles": [
    "<roles>"
  ],
  "capabilities": [
    "knowledge:read"
  ],
  "created_at": "2026-11-06T00:00:00Z"
}

读取主体

GET/v2/principals/{principal_id}

读取一个主体。需要 tenant_admin,且 Key 不受 Space 限制。本租户没有的 id 返回 404 not_found。不需要任何能力。

需要的能力 不检查能力。

参数

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

响应

错误状态

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

请求示例

curl
curl "https://api.mirabase.dev/v2/principals/$PRINCIPAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "id": "<id>",
  "kind": "human",
  "roles": [
    "<roles>"
  ],
  "capabilities": [
    "knowledge:read"
  ],
  "created_at": "2026-11-06T00:00:00Z"
}

修改主体能力

PATCH/v2/principals/{principal_id}

用 grant_capabilities 整体替换主体的能力:列表中没有的能力会被收回。受 Space 限制的 Key 不能调用。变更会写入审计日志。在有团队的账户中,Admin 的权限取决于归属关系:不能对 Owner 或其他 Admin 执行这些操作;对其他成员只能修改能力或吊销 Key,不能签发或轮换 Key;只能管理自己创建的 Agent 和最终用户。其他操作返回 403 forbidden;已移除的成员不能执行任何此类操作。需要 tenant_admin 角色,不需要任何能力。

需要的能力 不检查能力。

参数

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

请求体

application/json DevUpdatePrincipalRequest

字段类型说明
grant_capabilities必填DevCapability[]替换该主体的能力。你必须持有此列表中的全部能力,以及该主体现有的全部能力。

响应

错误状态

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

请求示例

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

响应结构示例

json
{
  "id": "<id>",
  "kind": "human",
  "roles": [
    "<roles>"
  ],
  "capabilities": [
    "knowledge:read"
  ],
  "created_at": "2026-11-06T00:00:00Z"
}