服务用户是用于 API 访问的专用机器人账号，并通过角色实现权限控制。这是所有新集成场景中推荐使用的身份验证方式。
- 在 Settings > Service users 中创建一个服务用户
- 为该服务用户分配角色，用于控制其可访问的端点
- 生成一个 API key（以
cog_ 开头）
- 在每个请求的
Authorization 标头中包含该 API key
curl -X POST "https://api.devin.ai/v3/organizations/sessions" \
-H "Authorization: Bearer $DEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Create a simple Python script"}'
| Scope | Created in | API access | Use case |
|---|
| Organization | 设置 > 服务用户 | /v3/organizations/* | 会话管理、Knowledge、playbooks、机密 |
| Enterprise | 企业设置 > 服务用户 | /v3/enterprise/* + /v3/organizations/* | 跨组织管理、分析、审计日志、计费 |
具有 Organization 作用域的服务用户在调用端点时，URL 中无需指定 {org_id}——系统会根据凭证自动解析。
使用 create_as_user_id 进行会话归因
create_as_user_id 参数。该会话会出现在该用户的会话列表中，并计入其使用量。
这要求该 service user 的角色拥有 ImpersonateOrgSessions 权限。
正在从个人 API key 迁移？ 个人 API key（v1/v2）会自动以你的个人身份创建会话。使用 service user 时，可通过 create_as_user_id 获得相同行为，并额外带来 RBAC、审计日志以及集中式密钥管理。示例参见 API Overview。
- 密钥以
cog_ 开头，并且只会在创建时显示一次
- 服务用户会在审计日志中与人工用户分开显示
- 权限通过 RBAC 控制——仅为集成分配其所需的权限
- Enterprise 服务用户会在所有组织中继承组织级别权限
有关详细的设置说明，请参阅 Teams 快速入门 或 Enterprise 快速入门。
旧版 API keys 正在被弃用，将由服务用户（service users）取代。我们建议将现有集成迁移到服务用户。请参阅迁移指南。 | Key 类型 | 前缀 | 使用范围 | 描述 |
|---|
| Personal API key | apk_user_ | v1, v2 | 绑定到用户帐户，继承该用户的权限 |
| Service API key | apk_ | v1 | 组织级，用于自动化 |
所有 Devin API 均采用 Bearer Token 身份验证方式。请在 Authorization 请求头中带上你的 key：
Authorization: Bearer your_api_key_here
切勿在 GitHub 仓库、客户端代码或日志等任何公开可访问区域共享 API key。
- 安全存储密钥：使用环境变量或机密管理系统
- 定期轮换密钥：定期生成新密钥并撤销旧密钥
- 在自动化中使用服务用户：生产环境中优先使用服务用户而非个人密钥
- 应用最小权限原则：仅授予完成任务所需的最低权限
- 监控使用情况：查看审计日志以发现异常的 API 活动
- 立即撤销已泄露密钥：如果密钥被暴露，立即撤销并生成新密钥
可能原因：
API key 无效或已过期- 缺少
Authorization 请求头
- Bearer token 格式不正确
解决方案： 核实你的 API key 是否正确，并确保在 Authorization 请求头中按要求正确填写和格式化。
可能原因：
- API key 不具有所需权限
- 针对该 endpoint 使用了错误的 key 类型（例如，用旧版 key 调用 v3 端点）
- 尝试访问超出你授权范围的资源
解决方案：
- 确认你的服务用户具备正确的角色和权限
- 对于旧版 v2 端点：确认你拥有 Enterprise 管理员角色
- 对于旧版 v1 端点：核实你是否有该组织的访问权限
可能原因：
- API 端点 URL 不正确
- 资源不存在，或你没有访问权限
解决方案： 验证端点 URL，并确认该资源确实存在。
