身份验证

Devin API 采用 主体 + 令牌 模型。主体表示你是谁 (即你的身份) ，而令牌则用于证明你的身份 (即你的凭据) 。理解这一区别，是根据你的使用场景选择合适身份验证方法的关键。

主体与令牌

主体	令牌	描述
Service User (非人类)	Service User API Key	用于自动化集成和 CI/CD 流水线
User (人类)	Personal Access Token (PAT)	用于以你的个人身份进行程序化访问

所有 API 凭据均采用 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/企业账户。

个人访问令牌 (PAT) 允许人工用户以自己的身份通过编程方式进行身份验证。当你使用 PAT 时，API 识别到的就是你——你的权限、你的 org 成员资格，以及你的审计记录。当你希望以你自己的身份发起 API 调用 (例如运行个人脚本或使用本地工具) ，而不是通过共享的服务用户时，这会非常有用。更多详情，请参阅个人访问令牌。

旧版身份验证 (已弃用)

旧版 API 密钥已弃用。请使用采用服务用户身份验证的 API v3。请参阅迁移指南。

旧版 API 密钥与 v1 和 v2 API 一起使用。它们在弃用过渡期内仍可用，但不支持 RBAC、会话归因或基于游标的分页等新功能。

密钥类型	前缀	搭配使用	描述
Personal API key	`apk_user_`	v1, v2	绑定到用户账户，继承该用户的权限
Service API key	`apk_`	v1	组织作用域，用于自动化

生成位置： Settings > API Keys

安全最佳实践

切勿在 GitHub 仓库、客户端代码或日志等任何公开可访问区域共享 API key。

安全存储密钥：使用环境变量或机密管理系统
定期轮换密钥：定期生成新密钥并撤销旧密钥
在自动化中使用服务用户：生产环境中优先使用服务用户而非个人密钥
应用最小权限原则：仅授予完成任务所需的最低权限
监控使用情况：查看审计日志以发现异常的 API 活动
立即撤销已泄露密钥：如果密钥被暴露，立即撤销并生成新密钥

故障排除

401 未授权

可能原因：

“ 无效或已过期
缺少 Authorization 请求头
Bearer token 格式不正确
将旧版 “ (apk_ / apk_user_) 与 Devin MCP 一起使用——仅支持带有 cog_ 前缀的密钥

解决方案： 核实你的

是否正确，并确保在 `Authorization` 请求头中按要求正确填写和格式化。对于 MCP 的使用，请确保你使用的是服务用户

(而非旧版密钥) 。

403 禁止访问

可能原因：

API key 不具有所需权限
针对该 endpoint 使用了错误的 key 类型 (例如，用旧版 key 调用 v3 端点)
尝试访问超出你授权范围的资源

解决方案：

确认你的服务用户具备正确的角色和权限
对于旧版 v2 端点：确认你拥有 Enterprise 管理员角色
对于旧版 v1 端点：核实你是否有该组织的访问权限

404 未找到

可能原因：

API 端点 URL 不正确
资源不存在，或你没有访问权限

解决方案： 验证端点 URL，并确认该资源确实存在。

后续步骤

Teams 快速入门 — 几分钟内上手
Enterprise 快速入门 — RBAC 和多组织架构配置
常见流程 — 端到端工作流程示例
迁移指南 — 从 v1/v2 迁移

快速开始

核心概念

Agent 生命周期

上下文管理

环境管理

自动化

集成

分析

可观测性

Devin for Security

基础架构

身份与访问控制

配置

旧版 API v1

旧版 API v2

主体与令牌

服务用户 (推荐用于自动化)

工作原理

服务用户作用域

使用 `create_as_user_id` 进行会话归因

主要属性

个人访问令牌 (封闭测试)

旧版身份验证 (已弃用)

安全最佳实践

故障排除

401 未授权

403 禁止访问

404 未找到

后续步骤

​主体与令牌

​服务用户 (推荐用于自动化)

​工作原理

​服务用户作用域

​使用 create_as_user_id 进行会话归因

​主要属性

​个人访问令牌 (封闭测试)

​旧版身份验证 (已弃用)

​安全最佳实践

​故障排除

​401 未授权

​403 禁止访问

​404 未找到

​后续步骤

主体与令牌

服务用户 (推荐用于自动化)

工作原理

服务用户作用域

使用 `create_as_user_id` 进行会话归因

主要属性

个人访问令牌 (封闭测试)

旧版身份验证 (已弃用)

安全最佳实践

故障排除

401 未授权

403 禁止访问

404 未找到

后续步骤