认证、工作空间与服务账号

选对凭据类型、显式锁定目标组织并做好密钥轮换,避免线上任务因成员离职失效或越权访问其他组织。完整字段定义见 API 参考。

四种凭据怎么选

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、问答集与外部连接都归属于具体的组织工作空间。不同凭据确定工作空间的方式不同:

# 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"

组织服务账号与无停机轮换

生产集成强烈建议使用组织服务账号而不是成员个人 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,按四步实现零停机轮换:

  1. 签发新 Key:为同一服务账号或账户签发一把新 Key,设置明确的描述与过期天数(例如 prod-sync-2026q4、90 天)。
  2. 灰度切换并验证:更新调用方密钥管理(Vault / K8s Secret),确认用新 Key 调用 GET /api/v2/auth/user 及核心读接口返回 200。
  3. 观察旧 Key 流量归零:通过列表接口检查旧 Key 的最近使用时间不再变化。
  4. 吊销旧 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

下一步