Devin API 采用 主体 + 令牌 模型。主体表示你是谁 (即你的身份) ，而令牌则用于证明你的身份 (即你的凭据) 。理解这一区别，是根据你的使用场景选择合适身份验证方法的关键。
| 主体 | 令牌 | 描述 |
|---|
| Service User (非人类) | Service User API Key | 用于自动化集成和 CI/CD 流水线 |
| User (人类) | Personal Access Token (PAT) | 用于以你的个人身份进行程序化访问 |
cog_ 前缀格式。请在每个请求的 Authorization 请求头中附上你的令牌：
curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
-H "Authorization: Bearer cog_your_token_here"
- Service User API 密钥 以服务用户身份进行认证——适用该服务用户的身份、权限和 org 成员资格。
- Personal Access Token 以创建它的人工用户身份进行认证——适用该用户的身份、权限和 org 成员资格。
服务用户是专为 API 集成设计的非人类账户。它们可通过 RBAC 分配特定权限，并可独立于人工用户添加到组织中。
- 在 Settings > Service users (组织) 或 Enterprise settings > Service users (企业) 中创建一个服务用户
- 为该服务用户分配一个角色，以控制其可访问的端点
- 生成一个 API 密钥——该密钥以
cog_ 开头，并且只会在创建时显示一次
- 在每个 API 请求的
Authorization 请求头中使用该密钥
curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
-H "Authorization: Bearer $DEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Create a simple Python script"}'
| 作用域 | 创建位置 | API 访问 | 使用场景 |
|---|
| Organization | Settings > Service users | /v3/organizations/* | 会话管理、知识、playbooks、密钥 |
| Enterprise | Enterprise settings > Service users | /v3/enterprise/* + /v3/organizations/* | 跨组织管理、分析、审计日志、计费 |
可在 Settings > Service users 页面找到你的组织 ID。
使用 create_as_user_id 进行会话归因
create_as_user_id 参数。该会话会出现在该用户的会话列表中，并计入其使用量。
这要求该服务用户的角色拥有 ImpersonateOrgSessions 权限。
- 密钥以
cog_ 开头，并且只会在创建时显示一次
- 服务用户会在审计日志中与人工用户分开显示
- 权限通过 RBAC 控制——仅为集成分配其所需的权限
- Enterprise 服务用户会在所有组织中继承组织级别权限
有关详细的设置说明，请参阅 Teams 快速入门 或 Enterprise 快速入门。
个人访问令牌目前处于封闭测试阶段，并受功能开关控制。联系支持团队以获取访问权限。PAT 不适用于 SSO/企业账户。
旧版 API 密钥与 v1 和 v2 API 一起使用。它们在弃用过渡期内仍可用，但不支持 RBAC、会话归因或基于游标的分页等新功能。
| 密钥类型 | 前缀 | 搭配使用 | 描述 |
|---|
| Personal API key | apk_user_ | v1, v2 | 绑定到用户账户，继承该用户的权限 |
| Service API key | apk_ | v1 | 组织作用域，用于自动化 |
切勿在 GitHub 仓库、客户端代码或日志等任何公开可访问区域共享 API key。
- 安全存储密钥：使用环境变量或机密管理系统
- 定期轮换密钥：定期生成新密钥并撤销旧密钥
- 在自动化中使用服务用户：生产环境中优先使用服务用户而非个人密钥
- 应用最小权限原则：仅授予完成任务所需的最低权限
- 监控使用情况：查看审计日志以发现异常的 API 活动
- 立即撤销已泄露密钥：如果密钥被暴露，立即撤销并生成新密钥
可能原因：
API key 无效或已过期- 缺少
Authorization 请求头
- Bearer token 格式不正确
解决方案： 核实你的 API key 是否正确，并确保在 Authorization 请求头中按要求正确填写和格式化。
可能原因：
- API key 不具有所需权限
- 针对该 endpoint 使用了错误的 key 类型 (例如，用旧版 key 调用 v3 端点)
- 尝试访问超出你授权范围的资源
解决方案：
- 确认你的服务用户具备正确的角色和权限
- 对于旧版 v2 端点：确认你拥有 Enterprise 管理员角色
- 对于旧版 v1 端点：核实你是否有该组织的访问权限
可能原因：
- API 端点 URL 不正确
- 资源不存在，或你没有访问权限
解决方案： 验证端点 URL，并确认该资源确实存在。
