使用个人访问令牌（PAT）或服务账号令牌（SAT）认证 Qoder Cloud Agents API 请求。
Qoder Cloud Agents API 支持两种 Bearer 令牌：PAT（Personal Access Token，个人访问令牌）和 SAT（Service Account Token，服务账号令牌）。每个 API 请求都必须在
置换 SAT 和调用业务 API 必须使用同一区域的地址。请设置以下服务地址：
调用 Service Token Exchange 接口，使用 SA Key 置换 SAT：
响应中的
如果服务端集成需要使用同一个 SAT 调用 Forward（
同一个 SAT 可分别调用两类 API：
使用 PAT 或 SAT 调用 Cloud Agents API 时，统一通过 Bearer 方式传递：
建议将当前选用的令牌设置为统一环境变量：
完整请求示例：
Authorization 头中携带其中一种有效令牌。
| 令牌 | 适用场景 | 获取方式 |
|---|---|---|
| PAT | 用户身份调用，适合个人开发和调试 | 在 Qoder 控制台中创建 |
| SAT | Service Account 身份调用，适合服务端集成和自动化 | 使用 Service Account API Key（SA Key）置换短期 JWT |
SA Key 是用于置换 SAT 的长期凭据，不应直接用于调用 Cloud Agents 业务接口。
选择服务区域
置换 SAT 和调用业务 API 必须使用同一区域的地址。请设置以下服务地址：
方式一：使用 PAT
获取 PAT
- 登录 Qoder 控制台
- 进入 设置 → 个人访问令牌
- 点击 创建令牌，设置名称、权限范围和有效期
- 复制生成的 PAT，并设置环境变量：
PAT 以
pt- 前缀开头，完整值仅在创建时显示一次。请勿将令牌提交到代码仓库或分享给他人。方式二：使用 Service Account 和 SAT
获取并设置 SA Key
- 使用组织管理员账号登录 Qoder 控制台
- 在组织管理中创建或选择 Service Account
- 在 Service Account 详情页创建 API Key。创建时无需选择 scope；所需 scope 在后续置换 SAT 时指定
- 复制 SA Key，并设置环境变量：
SA Key 的完整值仅在创建时显示一次。请将它保存在密钥管理系统中，不要写入代码或日志。
置换 SAT（JWT）
调用 Service Token Exchange 接口，使用 SA Key 置换 SAT：
| 字段 | 说明 |
|---|---|
grant_type | 固定为 client_credentials |
audience | 固定为 qoder |
scope | 在置换请求中指定：仅调用 Managed API 时使用 qca.access；同时调用 Forward 和 Managed API 时使用 qca.access forward.access。不能超出 SA Key 已配置的权限 |
ttl_seconds | SAT 有效期，单位为秒；最大为 43200（12 小时） |
access_token 即 SAT。SAT 过期后不能刷新，需要使用 SA Key 重新调用上述置换接口。
使用同一个 SAT 调用 Forward 和 Managed API
如果服务端集成需要使用同一个 SAT 调用 Forward（/api/v1/forward/*）和 Managed（/api/v1/cloud/*）API，请在置换时同时传入 qca.access 和 forward.access：
兼容现有接入方式
- 仅调用 Managed API 的现有集成可继续只申请和传入
qca.access。 - PAT 的获取和使用方式不变。
- 仅调用 Forward API，或需要精确吊销、绑定单个 Identity时，仍可通过 Forward Token 接口签发 SAT。
Bearer 头格式
使用 PAT 或 SAT 调用 Cloud Agents API 时，统一通过 Bearer 方式传递：
安全建议
- 为不同环境（开发/测试/生产）创建独立 PAT 或 SA Key
- 将 PAT 和 SA Key 存储在密钥管理系统中，不要硬编码
- 置换 SAT 时仅申请集成所需的最小 scope
- 在 SAT 过期前重新置换，并安全替换运行中的令牌
- 发现 PAT 或 SA Key 泄漏时，立即在控制台撤销或轮换