> ## 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.

# 个人访问令牌

> 以你自己的身份进行身份验证，以便通过程序访问 API

<div id="overview">
  ## 概述
</div>

个人访问令牌 (PAT) 允许真人用户以自己的身份通过编程方式进行身份验证。与服务用户 API key (以非人类服务用户的身份进行身份验证) 不同，PAT 会将你认证为 **你**——也就是创建该令牌的真人用户。

| 令牌类型 | 认证为 | 身份 | 权限 |
| - | - | - | - |
| **Service User API Key** | 服务用户 (非人类) | 服务用户的身份 | 服务用户被分配的角色 |
| **Personal Access Token** | 用户 (真人) | 你的用户身份 | 你的权限和 org 成员身份 |

所有 API 凭证都使用 `cog_` 前缀格式。这两种令牌类型在 `Authorization` 请求头中的用法完全相同：

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $YOUR_PAT"
```

<div id="scope-and-permissions">
  ## 作用域和权限
</div>

PAT 归属于你的账户 (Teams 账户或企业账户) ，且属于你本人。它不与某个组织绑定，也不存在“组织 PAT”或“企业 PAT”。这与[服务用户](/zh/api-reference/authentication#service-user-scopes)不同，服务用户可在组织级别或企业级别创建。

| | 个人访问令牌 |
| - | - |
| **归属** | 账户中的你的用户 |
| **管理位置** | 任意组织或企业设置中的 **Settings > Devin API** 下的 **PATs** 选项卡 |
| **可调用的端点** | 你有访问权限的每个组织的 `/v3/organizations/{org_id}/*`；如果你拥有相应的企业权限，则还可调用 `/v3/enterprise/*` |

每个请求都会指定组织。组织端点会在 URL 路径中标明组织 (`/v3/organizations/{org_id}/...`) ，并根据你在该组织中的访问权限和角色对请求进行授权。对你无权访问的组织发起请求会失败。

令牌拥有与你的用户相同的权限。你能在 web app 中执行的任何操作，也都可以通过 PAT 执行，不会获得额外权限。

要创建、轮换或撤销 PAT，你需要在当前查看设置的组织中拥有 **Manage API keys** 权限，或在账户级别拥有 **管理账户 API 密钥** 权限。此权限决定谁可以管理令牌；不会改变令牌可执行的操作。

企业账户还包含一个仅用于存储企业范围内设置的内部组织。它不是工作区。以该组织为目标的 PAT 请求会被拒绝并返回 `403`，因此请始终使用子组织 ID。

<div id="when-to-use-pats">
  ## 何时使用 PAT
</div>

PAT 适用于需要**以你本人身份**通过程序访问 API 的场景：

* **个人脚本和工具** — 无需共享服务用户，即可自动化你自己的工作流程
* **本地开发** — 使用你自己的账户测试 API 集成
* **短期自动化** — 应归因于你的一次性脚本

对于生产集成、CI/CD 流水线和共享自动化，请改用[服务用户 API key](/zh/api-reference/authentication#service-users-recommended-for-automation)。服务用户可提供更完善的审计记录、集中式密钥管理和 RBAC 控制。如果你不确定该使用哪一种，请参阅[比较](/zh/api-reference/authentication#personal-access-token-or-service-user)。

<div id="creating-and-managing-pats">
  ## 创建和管理 PAT
</div>

你可以在任意组织或企业设置中的 **Devin API** 设置页面的 **PAT** 选项卡中管理 PAT。无论通过哪种方式，该选项卡显示的都是相同的令牌 (请参阅[作用域和权限](#scope-and-permissions)) 。

1. **创建 PAT** — 为其设置名称和到期日期。令牌以 `cog_` 开头，且仅在创建时显示一次。
2. **使用令牌** — 在 `Authorization` 标头中使用该令牌，其用法与服务用户 API key 完全相同。每次 API 调用都会以你的用户账户身份进行身份验证：你的权限、组织成员资格和审计记录均会适用。
3. **轮换 PAT** — 为现有令牌生成新的密钥而不更改其名称；旧密钥会立即失效。
4. **撤销 PAT** — 可随时使令牌失效。

PAT 也可用于 ACP 实时 WebSocket 等实时端点，因此 Devin CLI 和桌面客户端等工具可使用 PAT 进行身份验证。

<div id="enterprise-governance">
  ## Enterprise 治理
</div>

对于 Enterprise 账户，PAT 的可用性由适用于该 Enterprise 下所有组织的企业范围内 **PAT 策略** 控制。拥有 **管理企业设置** 权限的 Enterprise Admin 可在 Enterprise **Devin API** 设置页面的 **PAT 策略** 选项卡中配置此策略 (并处理批准请求) 。

<div id="policy-modes">
  ### 策略模式
</div>

| 模式 | 行为 |
| - | - |
| **已禁用** (默认) | 成员无法创建或使用 PAT |
| **需要批准** | 成员提交 PAT 请求后，Enterprise Admin 必须批准该请求，才能创建令牌 |
| **自助服务** | 成员可以直接创建 PAT，但须遵守有效期策略 |

<div id="expiration-policy">
  ### 有效期策略
</div>

为 Enterprise 启用 PAT 后，每个 PAT **都必须设置到期日期**，且有效期不得超过策略规定的最长时限 (默认 **365 天**；Admin 可设置更短的上限) 。非 Enterprise (Teams) 账户可创建永不过期的 PAT。

<div id="approval-workflow">
  ### 批准工作流程
</div>

在**需要批准**模式下：

1. 成员可在 PATs 选项卡中申请 PAT (名称和到期时间) 。
2. Enterprise Admin 会在**批准队列**中查看该申请，并予以批准或拒绝。
3. 申请获批后，成员完成申请以生成令牌 (仅显示一次) 。
4. 待处理的申请如在 **7 天**内未获处理，将自动失效。

在令牌生命周期的每个阶段 (已申请、已批准、已拒绝、已撤销) ，申请人和 Admin 都会收到电子邮件通知。

<div id="token-inventory-and-revocation">
  ### 令牌清单与撤销
</div>

拥有 **管理账户 API 密钥** 权限的 Enterprise Admin 可以：

* 在令牌清单中**查看整个 Enterprise 的所有 PAT**，包括其是否符合当前策略
* **批量撤销**令牌 (例如，在收紧策略后)

收紧策略 (或禁用 PAT) 会取消受影响的申请，并在清单中标记不再符合要求的现有令牌。

<div id="automatic-revocation">
  ### 自动撤销
</div>

当用户不再是账户成员时，其 PAT 将被自动撤销，包括通过 SCIM 取消预配或 IdP 组变更而被移除的情况。

<div id="security-considerations">
  ## 安全注意事项
</div>

* 像对待密码一样谨慎保管 PAT——它们可授予对你账户的完全访问权限
* 将 PAT 存储在环境变量或密钥管理服务中，绝不要存放在源代码里
* 设置适合你的使用场景的最短有效期
* 如果 PAT 泄露，请立即将其撤销
* 对于任何共享或生产环境中的自动化，优先使用服务用户 API key

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

* [身份验证概述](/zh/api-reference/authentication) — 了解完整的身份验证模型
* [Teams 快速开始](/zh/api-reference/getting-started/teams-quickstart) — 开始使用服务用户


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.