> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 身份验证

> 了解主体、令牌，以及如何使用 Devin API 进行身份验证

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

<div id="principals-tokens">
  ## 主体与令牌
</div>

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

所有 API 凭据均采用 `cog_` 前缀格式。请在每个请求的 `Authorization` 请求头中附上你的令牌：

```bash theme={null}
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 成员资格。

***

<div id="service-users-recommended-for-automation">
  ## 服务用户 (推荐用于自动化)
</div>

服务用户是专为 API 集成设计的非人类账户。它们可通过 RBAC 分配特定权限，并可独立于人工用户添加到组织中。

<div id="how-it-works">
  ### 工作原理
</div>

1. 在 **Settings > Service users** (组织) 或 **Enterprise settings > Service users** (企业) 中**创建一个服务用户**
2. 为该服务用户**分配一个角色**，以控制其可访问的端点
3. **生成一个 API 密钥**——该密钥以 `cog_` 开头，并且只会在创建时显示一次
4. 在每个 API 请求的 `Authorization` 请求头中**使用该密钥**

```bash theme={null}
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"}'
```

<div id="service-user-scopes">
  ### 服务用户作用域
</div>

| 作用域              | 创建位置                                | API 访问                                     | 使用场景                 |
| ---------------- | ----------------------------------- | ------------------------------------------ | -------------------- |
| **Organization** | Settings > Service users            | `/v3/organizations/*`                      | 会话管理、知识、playbooks、密钥 |
| **Enterprise**   | Enterprise settings > Service users | `/v3/enterprise/*` + `/v3/organizations/*` | 跨组织管理、分析、审计日志、计费     |

<Tip>
  可在 **Settings > Service users** 页面找到你的组织 ID。
</Tip>

<div id="session-attribution-with-create_as_user_id">
  ### 使用 `create_as_user_id` 进行会话归因
</div>

服务用户与人工用户是不同的身份。默认情况下，由服务用户创建的会话会归因到服务用户本身。若要**代表某个特定用户**创建会话，在创建会话时传入 `create_as_user_id` 参数。该会话会出现在该用户的会话列表中，并计入其使用量。

这要求该服务用户的角色拥有 `ImpersonateOrgSessions` 权限。

<div id="key-properties">
  ### 主要属性
</div>

* 密钥以 `cog_` 开头，并且只会在创建时显示一次
* 服务用户会在审计日志中与人工用户分开显示
* 权限通过 RBAC 控制——仅为集成分配其所需的权限
* Enterprise 服务用户会在所有组织中继承组织级别权限

有关详细的设置说明，请参阅 [Teams 快速入门](/zh/api-reference/getting-started/teams-quickstart) 或 [Enterprise 快速入门](/zh/api-reference/getting-started/enterprise-quickstart)。

***

<div id="personal-access-tokens-closed-beta">
  ## 个人访问令牌 (封闭测试)
</div>

<Note>
  个人访问令牌目前处于**封闭测试**阶段，并受功能开关控制。[联系支持团队](mailto:support@cognition.ai)以获取访问权限。PAT 不适用于 SSO/企业账户。
</Note>

个人访问令牌 (PAT) 允许人工用户以自己的身份通过编程方式进行身份验证。当你使用 PAT 时，API 识别到的就是**你**——你的权限、你的 org 成员资格，以及你的审计记录。

当你希望以你自己的身份发起 API 调用 (例如运行个人脚本或使用本地工具) ，而不是通过共享的服务用户时，这会非常有用。

更多详情，请参阅[个人访问令牌](/zh/api-reference/personal-access-tokens)。

***

<div id="legacy-authentication-deprecated">
  ## 旧版身份验证 (已弃用)
</div>

<Warning>
  旧版 API 密钥已弃用。请使用采用服务用户身份验证的 [API v3](/zh/api-reference/v3/overview)。请参阅[迁移指南](/zh/api-reference/getting-started/migration-guide)。
</Warning>

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

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

**生成位置：** [Settings > API Keys](https://app.devin.ai/settings/api-keys)

***

<div id="security-best-practices">
  ## 安全最佳实践
</div>

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

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

<div id="troubleshooting">
  ## 故障排除
</div>

<div id="401-unauthorized">
  ### 401 未授权
</div>

**可能原因：**

* \`\` 无效或已过期
* 缺少 `Authorization` 请求头
* Bearer token 格式不正确
* 将旧版 \`\` (`apk_` / `apk_user_`) 与 [Devin MCP](/zh/work-with-devin/devin-mcp) 一起使用——仅支持带有 `cog_` 前缀的密钥

**解决方案：** 核实你的 ``是否正确，并确保在 `Authorization` 请求头中按要求正确填写和格式化。对于 MCP 的使用，请确保你使用的是服务用户`` (而非旧版密钥) 。

<div id="403-forbidden">
  ### 403 禁止访问
</div>

**可能原因：**

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

**解决方案：**

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

<div id="404-not-found">
  ### 404 未找到
</div>

**可能原因：**

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

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

<div id="next-steps">
  ## 后续步骤
</div>

* [Teams 快速入门](/zh/api-reference/getting-started/teams-quickstart) — 几分钟内上手
* [Enterprise 快速入门](/zh/api-reference/getting-started/enterprise-quickstart) — RBAC 和多组织架构配置
* [常见流程](/zh/api-reference/common-flows) — 端到端工作流程示例
* [迁移指南](/zh/api-reference/getting-started/migration-guide) — 从 v1/v2 迁移