四种凭据怎么选
ApeMind 严格区分「人在交互」和「系统在运行」两类身份。不要把个人登录凭据塞进服务端脚本,也不要用 API Key 尝试调用平台管理接口。
| 凭据类型 | 认证头 | 权限边界 | 适用场景 |
|---|---|---|---|
| 组织服务账号 API Key | Authorization: Bearer <KEY> |
固定绑定所属组织;权限由服务账号的组织角色决定,不随任何成员离职失效 | 生产后端集成、CI/CD 知识同步、A2A 调用(服务端首选) |
| Agent API 密钥 | Authorization: Bearer <KEY> |
属于目标 Agent 的独立运行身份,只放行该 Agent 的 Chat / Turn 接口,且按密钥隔离会话 | 只允许外部业务系统调用单个 Agent 对话,见Agent 访问密钥 |
| 成员 API Key | Authorization: Bearer <KEY> |
绑定单个组织,受成员角色与 Key 作用域交集约束;不继承账户管理与平台管理员权限 | 个人开发调试、把 Cursor / Claude Code 接入 MCP Server |
| OAuth Access Token | Authorization: Bearer <TOKEN>+ X-ApeMind-Workspace-Id |
按授权 scope(如 knowledge.read、turn.read、agent.write)受限,支持访问原生 SSE 事件流与多组织切换 |
apemind CLI、Desktop 客户端与需要交互授权的桌面工具 |
同一个请求同时携带 Authorization: Bearer 和浏览器 session Cookie 会被鉴权层拒绝(401),不会静默回退到 Cookie。服务端代码应只发送 Authorization 头。
工作空间选择与 X-ApeMind-Workspace-Id
ApeMind 的知识库、Agent、问答集与外部连接都归属于具体的组织工作空间。不同凭据确定工作空间的方式不同:
- API Key(成员 / 服务账号 / Agent Key):在创建时已经绑定目标组织,服务端直接按绑定组织路由,无法通过请求头或查询参数跨到其他组织,也不能调用
/api/v2/me/workspaces枚举其他组织。 - OAuth 与浏览器会话:登录成功不等于已经选定工作空间。调用任何组织资源或 MCP 工具前,先查询可用工作空间列表,再将选中的组织 ID 放入请求头或路径参数:
# 1. 查询当前身份可访问的工作空间
curl --fail-with-body \
-H "Authorization: Bearer ${OAUTH_ACCESS_TOKEN}" \
"${APEMIND_BASE_URL}/api/v2/me/workspaces"
# 2. 携带选中的组织 ID 调用业务接口或 MCP
curl --fail-with-body \
-H "Authorization: Bearer ${OAUTH_ACCESS_TOKEN}" \
-H "X-ApeMind-Workspace-Id: ${APEMIND_ORG_ID}" \
"${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/agents"
- 如果当前账户尚未加入任何组织,
GET /api/v2/me/workspaces会返回合法的空数组items: [];此时账户级接口可用,但需要组织命名空间的请求会返回workspace_required,调用方应引导用户加入组织,不要自行拼接历史格式的工作空间 ID。 - 对声明式配置和连接等路径带
/api/v2/workspaces/{workspace_id}/...的接口,路径中的{workspace_id}即组织 ID,须与凭据绑定组织或X-ApeMind-Workspace-Id一致。
组织服务账号与无停机轮换
生产集成强烈建议使用组织服务账号而不是成员个人 Key:服务账号拥有独立的组织角色(遵循最小权限),即使创建它的管理员离开组织,线上集成依然正常运行。创建组织 Agent 时,平台也会自动为 Agent 生成独立的运行服务身份,无需额外转移所有权。
1. 创建服务账号并签发密钥
需要具备组织 organization_credential.manage 权限(通常为组织 Owner / Admin)。服务账号密钥签发属于高敏感操作,支持在 Web 控制台「组织设置 › 服务账号」完成,或使用管理员浏览器会话调用接口:
# 创建服务账号(可通过 CLI 预演并执行)
apemind org service-account create contract-sync \
--org-id "${APEMIND_ORG_ID}" \
--role-id "<ROLE_ID>" \
--dry-run
apemind org service-account create contract-sync \
--org-id "${APEMIND_ORG_ID}" \
--role-id "<ROLE_ID>" \
--confirm
随后在「组织设置 › 服务账号」中为该账号签发密钥(可设置 expires_in_days 有效期)。完整密钥明文仅在签发响应中返回一次,后续列表接口只返回脱敏后的 key_masked。
2. 双 Key 平滑轮换
同一个服务账号(或成员账户)可以同时持有多个有效 API Key,按四步实现零停机轮换:
- 签发新 Key:为同一服务账号或账户签发一把新 Key,设置明确的描述与过期天数(例如
prod-sync-2026q4、90 天)。 - 灰度切换并验证:更新调用方密钥管理(Vault / K8s Secret),确认用新 Key 调用
GET /api/v2/auth/user及核心读接口返回200。 - 观察旧 Key 流量归零:通过列表接口检查旧 Key 的最近使用时间不再变化。
- 吊销旧 Key:吊销后使用旧 Key 的请求立即返回
401。
3. 组织级审查与紧急吊销
组织管理员可以统一查看本组织下所有成员和服务账号绑定的 API Key(含持有者、是否仍在组织内、最近使用时间),并在密钥泄露或人员变动时一键吊销:
# 查看组织内全部 API Key(脱敏显示)
apemind org api-key list --org-id "${APEMIND_ORG_ID}" --format json
# 立即吊销指定密钥
apemind org api-key revoke "<API_KEY_ID>" --org-id "${APEMIND_ORG_ID}" --confirm
# 停用并删除整个服务账号(同时立即吊销其名下全部密钥,不可恢复)
apemind org service-account delete "<ACCOUNT_ID>" --org-id "${APEMIND_ORG_ID}" --confirm
平台托管的内部保护密钥(is_protected: true)不允许直接吊销,请求会返回 409 PROTECTED_API_KEY,需通过停用或删除对应资源来回收。
常见鉴权错误速查
| HTTP 状态 / 错误码 | 典型原因 | 处理方式 |
|---|---|---|
401 Unauthorized |
密钥无效、已过期、已被吊销,或同时发送了 API Key 与 Cookie | 检查密钥状态;移除冗余 Cookie,仅保留单一认证方式 |
403 Forbidden |
角色缺少所需权限、API Key 超出绑定作用域,或用 API Key 调用了仅限会话的管理接口 / 原生 SSE 流 | 核对角色权限与 Key 作用域;管理类操作改用 OAuth/会话,SSE 改用轮询或 OpenAI 兼容流 |
400 / workspace_required |
OAuth 请求未带 X-ApeMind-Workspace-Id,或账户未加入任何可用组织 |
先调 GET /api/v2/me/workspaces 获取有效组织 ID 并随请求发送 |
409 workspace_stale |
历史个人工作空间已迁移至组织,客户端仍在写入旧路径 | 刷新 /api/v2/me/workspaces 并切换为迁移后的组织 ID |