主体、能力、Space 角色、读写根路径和 API Key 的限制如何共同决定一次请求。
请求的判定
一次请求必须同时满足以下条件,任一条件不满足即被拒绝:
allowed = capability in (principal.capabilities ∩ key.capabilities)
and space in key.allowed_space_ids (when set)
and the Space role is sufficient
and the path is under the member's read_root / write_root (when set)主体
| 类型 | 说明 |
|---|---|
| 人 | kind: human,可以具备 tenant_admin 角色 |
| Agent | kind: agent,有自己的权限、记忆和审计身份 |
| API Key | 凭据,不是主体,只能收窄所属主体 |
主体没有显示名,请自行按 id 记录名称。POST /v2/principals 只能创建 human 和 agent,tenant_admin 角色不能通过 API 授予。
能力
能力是对一类操作的许可,例如 knowledge:read、knowledge:write、knowledge:manage、knowledge:answer 和 memory:confirm。一个 API Key 的有效能力是主体能力和 Key 能力的交集。GET /v2/whoami 的 effective_capabilities 给出这个交集。
每种能力允许的操作见参考页的 DevCapability;每个操作需要的能力写在参考页该操作的条目里。
Space 角色
成员在每个 Space 中有一个角色:owner、editor 或 viewer。一次操作既要求能力,也要求最低角色。各角色可执行的操作见 DevSpaceRole;每个操作需要的能力和更严格的规则,见 API 参考 中该操作的说明。
Space 所有者用 PUT /v2/spaces/{space_id}/members/{principal_id} 设置成员的角色、write_mode、write_root 和 read_root。
Agent 的写入模式
write_mode 只对 Agent 生效,且只针对不属于它的文件。新成员默认为 proposal:修改他人的文件返回 403 proposal_required,移动和删除也一样,不会创建任何内容。设为 direct 后可以直接写入。Space 所有者始终是 direct。
proposal 模式的 Agent 可以带 Prefer: handling=proposal 把这类写入变成提案,由审核人批准,见 提案。
写入根路径和读取根路径
Space 所有者可以在设置成员时把它限制在一棵子树内。两种根路径都只会收窄:角色、能力和 API Key 的限制照常生效,没有拒绝规则。取值规则见 write_root 和 read_root。
# The Agent reads /projects/acme and writes only under /projects/acme/drafts.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$AGENT_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"role": "editor", "write_mode": "direct",
"read_root": "/projects/acme", "write_root": "/projects/acme/drafts"}'| 根路径 | 范围内 | 范围外 |
|---|---|---|
write_root | 在该目录下写入,不能重命名、移动或删除目录本身 | 403 outside_write_root,读取不受影响 |
read_root | 读取该目录及其下所有内容;没有 write_root 时也在此写入 | 404,与不存在相同;检索、上下文、记忆和变更流都不包含范围外的内容 |
- 没有路径的 Entry(
ingest、项目记忆、提炼的事实)在两种范围之外,成员自己的 Agent 记忆除外。 - 读取根路径和写入根路径在目录重命名或移动后仍然有效。删除某个成员的读取根路径或写入根路径,或包含这些路径的目录时,服务返回 409
directory_is_write_root或directory_is_read_root,Space 所有者执行此操作时也是如此。 write_root不限制分支;合并写入主线时逐个路径检查,全部通过或全部不生效。GET /v2/spaces和GET /v2/spaces/{space_id}返回你自己的read_root和write_root,从那里开始读tree。
为 Agent 配置权限
为 Agent 创建独立的主体,不要共用人的 API Key。这样它的写入、记忆和审计都有自己的身份,吊销时不影响他人。
# 1. Create the Agent. Without grant_capabilities it gets knowledge:read.
curl -X POST https://api.mirabase.dev/v2/principals \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind": "agent", "grant_capabilities": ["knowledge:read", "knowledge:write"]}'
# 2. Make it a member of one Space. write_mode direct lets it change files it does not own.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$AGENT_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"role": "editor", "write_mode": "direct"}'
# 3. Issue its key, narrowed to that Space.
curl -X POST https://api.mirabase.dev/v2/api-keys \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"actor_id": "'$AGENT_ID'", "name": "docs-agent",
"grant_capabilities": ["knowledge:read", "knowledge:write"],
"allowed_space_ids": ["'$SPACE_ID'"]}'按 Space 限定 API Key
- 访问收窄范围外的 Space 时,服务返回 404,与 Space 不存在时的响应相同。
- 受范围限制的 API Key 不能访问账户级和租户级功能:账户记忆、
GET /v2/principals、GET /v2/api-keys、GET /v2/audit/events。 - 比所属主体窄的 Key 只能为该主体签发 Key,因此切换身份也无法绕过限制。
不可见即不存在
看不见的资源和不存在的资源返回同一个 404。收到 403 时查看 GET /v2/whoami,收到 404 时检查 id、Key 的 Space 范围和成员关系。
审计
GET /v2/audit/events 返回治理和访问事件。事件只含标识符,不含用户内容。治理动作与它所做的修改在同一事务里记录,失败时一起回滚。
下一步
- 认证与 API Key:创建、轮换和吊销 Key。
- 文件与版本:提案的提交和审核。
- 错误码:403 的各个错误码分别表示什么。
