Devin 提供多个 API 版本，它们使用不同的身份验证机制和授权模型。了解应使用哪种 API key 类型对于正确集成至关重要。
| Version | Authentication | Authorization Model |
|---|
| v1 | 个人 API key 或服务 API key | 组织级 |
| v2 | 个人 API key | 仅限 Enterprise 管理员 |
| v3 (Beta) | 服务用户凭证 | 完整 RBAC |
| API Key 类型 | 前缀 | 描述 |
|---|
| Personal API Key | apk_user_ | 以用户-组织为作用域的密钥，继承对应个人用户的权限 |
| Service API Key | apk_ | 以组织为作用域的服务密钥，用于自动化 |
| Service User Credential | cog_ | 适用于 Enterprise/组织的服务用户凭据，支持 RBAC |
- v1：支持 — 继承用户的组织级权限
- v2：支持 — 仅适用于具有 Enterprise Admin 角色的用户
- v3：不支持 — 请改用 Service User Credentials（服务用户凭证）
推荐使用场景：
安全注意事项：
- key 的权限范围受限于用户自身的权限
- 撤销用户访问权限会自动使其 API key 失效
- 应定期轮换 key
在满足特定条件时，可在子组织中生成 Service API keys。
生成位置：
支持的 API 版本：
- v1：支持 — 作用范围限定为该组织
- v2：不支持
- v3：不支持 — 请改用 Service User Credentials
推荐使用场景：
- 组织级自动化
- 作用范围限定到特定团队的 CI/CD 流水线
- 子组织内的共享工具
服务用户是具有特定角色和权限的专用账户，用于基于 API 的自动化，并提供完整的 RBAC 支持。
生成位置：
服务用户类型：
- Enterprise Service Users：可根据分配的角色访问多个组织
- Organization Service Users：作用范围限定在特定组织内，具有组织级角色
支持的 API 版本：
- v1：不支持 - 不可用
- v2：不支持 - 不可用
- v3：支持 - 具备完整 RBAC 支持
推荐使用场景：
- 生产环境自动化，需细粒度权限控制
- 多组织工作流
- 对合规要求敏感且需要审计追踪的集成
- 具有特定权限范围的长期运行集成
安全注意事项：
- 服务用户会在审计日志中与人类用户单独记录
- 可通过 RBAC 精确控制权限
- 可轮换密钥而不影响人类用户账户
- 非常适合实施最小权限原则
所有 Devin API 均采用 Bearer Token 身份验证方式。请在 Authorization 请求头中带上你的 API key：
Authorization: Bearer your_api_key_here
curl -X POST "https://api.devin.ai/v1/sessions" \
-H "Authorization: Bearer YOUR_V1_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "创建一个简单的 Python 脚本"
}'
curl -X GET "https://api.devin.ai/v2/enterprise/organizations" \
-H "Authorization: Bearer YOUR_V2_ENTERPRISE_ADMIN_KEY"
curl -X GET "https://api.devin.ai/v3beta1/enterprise/organizations" \
-H "Authorization: Bearer YOUR_V3_SERVICE_USER_KEY"
切勿在 GitHub 仓库、客户端代码或日志等任何公开可访问区域共享 API key。
- 安全存储密钥：使用环境变量或机密管理系统
- 定期轮换密钥：定期生成新密钥并撤销旧密钥
- 在自动化中使用服务用户：生产环境中优先使用 v3 服务用户而非个人密钥
- 应用最小权限原则：仅授予完成任务所需的最低权限
- 监控使用情况：查看审计日志以发现异常的 API 活动
- 立即撤销已泄露密钥：如果密钥被暴露，立即撤销并生成新密钥
可能原因：
API key 无效或已过期- 缺少
Authorization 请求头
- Bearer token 格式不正确
解决方案： 核实你的 API key 是否正确，并确保在 Authorization 请求头中按要求正确填写和格式化。
可能原因：
- API key 不具有所需权限
- 针对你的 key 类型使用了错误的 API 版本（例如，个人 key 搭配 v3）
- 尝试访问超出你授权范围的资源
解决方案：
- 对于 v2：确认你拥有 Enterprise 管理员角色
- 对于 v3：使用具备相应角色的服务用户凭据
- 对于 v1：核实你是否有该组织的访问权限
可能原因：
- API 端点 URL 不正确
- 资源不存在，或你没有访问权限
解决方案： 验证端点 URL 是否与正在使用的 API 版本一致，并确认该资源确实存在。
