概述
所有 API 凭证都使用
cog_ 前缀格式。这两种令牌类型在 Authorization 请求头中的用法完全相同：
作用域和权限
每个请求都会指定组织。组织端点会在 URL 路径中标明组织 (
/v3/organizations/{org_id}/...) ，并根据你在该组织中的访问权限和角色对请求进行授权。对你无权访问的组织发起请求会失败。
令牌拥有与你的用户相同的权限。你能在 web app 中执行的任何操作，也都可以通过 PAT 执行，不会获得额外权限。
要创建、轮换或撤销 PAT，你需要在当前查看设置的组织中拥有 Manage API keys 权限，或在账户级别拥有 管理账户 API 密钥 权限。此权限决定谁可以管理令牌；不会改变令牌可执行的操作。
企业账户还包含一个仅用于存储企业范围内设置的内部组织。它不是工作区。以该组织为目标的 PAT 请求会被拒绝并返回 403，因此请始终使用子组织 ID。
何时使用 PAT
- 个人脚本和工具 — 无需共享服务用户，即可自动化你自己的工作流程
- 本地开发 — 使用你自己的账户测试 API 集成
- 短期自动化 — 应归因于你的一次性脚本
创建和管理 PAT
- 创建 PAT — 为其设置名称和到期日期。令牌以
cog_开头，且仅在创建时显示一次。 - 使用令牌 — 在
Authorization标头中使用该令牌，其用法与服务用户 API key 完全相同。每次 API 调用都会以你的用户账户身份进行身份验证：你的权限、组织成员资格和审计记录均会适用。 - 轮换 PAT — 为现有令牌生成新的密钥而不更改其名称；旧密钥会立即失效。
- 撤销 PAT — 可随时使令牌失效。
Enterprise 治理
策略模式
有效期策略
批准工作流程
- 成员可在 PATs 选项卡中申请 PAT (名称和到期时间) 。
- Enterprise Admin 会在批准队列中查看该申请，并予以批准或拒绝。
- 申请获批后，成员完成申请以生成令牌 (仅显示一次) 。
- 待处理的申请如在 7 天内未获处理，将自动失效。
令牌清单与撤销
- 在令牌清单中查看整个 Enterprise 的所有 PAT，包括其是否符合当前策略
- 批量撤销令牌 (例如，在收紧策略后)
自动撤销
安全注意事项
- 像对待密码一样谨慎保管 PAT——它们可授予对你账户的完全访问权限
- 将 PAT 存储在环境变量或密钥管理服务中，绝不要存放在源代码里
- 设置适合你的使用场景的最短有效期
- 如果 PAT 泄露，请立即将其撤销
- 对于任何共享或生产环境中的自动化，优先使用服务用户 API key
后续步骤
- 身份验证概述 — 了解完整的身份验证模型
- Teams 快速开始 — 开始使用服务用户