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

# 认证

> 使用个人访问令牌（PAT）或服务账号令牌（SAT）认证 Qoder Cloud Agents API 请求。

Qoder Cloud Agents API 支持两种 Bearer 令牌：<strong>PAT（Personal Access Token，个人访问令牌）</strong>和 <strong>SAT（Service Account Token，服务账号令牌）</strong>。每个 API 请求都必须在 `Authorization` 头中携带其中一种有效令牌。

| 令牌  | 适用场景                             | 获取方式                                       |
| --- | -------------------------------- | ------------------------------------------ |
| PAT | 用户身份调用，适合个人开发和调试                 | 在 Qoder 控制台中创建                             |
| SAT | Service Account 身份调用，适合服务端集成和自动化 | 使用 Service Account API Key（SA Key）置换短期 JWT |

<Note>SA Key 是用于置换 SAT 的长期凭据，不应直接用于调用 Cloud Agents 业务接口。</Note>

<a id="select-a-service-region" style={{ display: "block", scrollMarginTop: "calc(max(var(--topbar-height, 112px), calc(var(--topbar-height-h5, 62px) + 40px)) + 8px)" }} />

## 选择服务区域

置换 SAT 和调用业务 API 必须使用同一区域的地址。请设置以下服务地址：

```bash
export QODER_OPENAPI_BASE_URL="https://openapi.qoder.com.cn"
export QODER_API_BASE_URL="https://api.qoder.com.cn"
```

<a id="option-1-use-a-pat" style={{ display: "block", scrollMarginTop: "calc(max(var(--topbar-height, 112px), calc(var(--topbar-height-h5, 62px) + 40px)) + 8px)" }} />

## 方式一：使用 PAT

<a id="obtain-a-pat" style={{ display: "block", scrollMarginTop: "calc(max(var(--topbar-height, 112px), calc(var(--topbar-height-h5, 62px) + 40px)) + 8px)" }} />

### 获取 PAT

1. 登录 [Qoder 控制台](https://qoder.cn)
2. 进入 **设置 → 个人访问令牌**
3. 点击 **创建令牌**，设置名称、权限范围和有效期
4. 复制生成的 PAT，并设置环境变量：

```bash
export QODER_PAT="pt-your-token-here"
```

<Note>PAT 以 `pt-` 前缀开头，完整值仅在创建时显示一次。请勿将令牌提交到代码仓库或分享给他人。</Note>

<a id="option-2-use-a-service-account-and-sat" style={{ display: "block", scrollMarginTop: "calc(max(var(--topbar-height, 112px), calc(var(--topbar-height-h5, 62px) + 40px)) + 8px)" }} />

## 方式二：使用 Service Account 和 SAT

<a id="obtain-and-configure-an-sa-key" style={{ display: "block", scrollMarginTop: "calc(max(var(--topbar-height, 112px), calc(var(--topbar-height-h5, 62px) + 40px)) + 8px)" }} />

### 获取并设置 SA Key

1. 使用组织管理员账号登录 Qoder 控制台
2. 在组织管理中创建或选择 Service Account
3. 在 Service Account 详情页创建 API Key。创建时无需选择 scope；所需 scope 在后续置换 SAT 时指定
4. 复制 SA Key，并设置环境变量：

```bash
export QODER_SA_KEY="sa-key"
```

<Note>SA Key 的完整值仅在创建时显示一次。请将它保存在密钥管理系统中，不要写入代码或日志。</Note>

<a id="exchange-the-sa-key-for-an-sat-jwt" style={{ display: "block", scrollMarginTop: "calc(max(var(--topbar-height, 112px), calc(var(--topbar-height-h5, 62px) + 40px)) + 8px)" }} />

### 置换 SAT（JWT）

调用 Service Token Exchange 接口，使用 SA Key 置换 SAT：

```bash
SAT_RESPONSE=$(curl --silent --show-error --location "$QODER_OPENAPI_BASE_URL/api/v1/serviceToken/exchange" \
  --header "Authorization: Bearer $QODER_SA_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "audience": "qoder",
    "scope": "qca.access",
    "ttl_seconds": 43200
  }')

export QODER_SAT="$(printf '%s' "$SAT_RESPONSE" | jq -r '.access_token')"
```

| 字段            | 说明                                                                                                                      |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `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 重新调用上述置换接口。

<a id="use-one-sat-for-forward-and-managed-apis" style={{ display: "block", scrollMarginTop: "calc(max(var(--topbar-height, 112px), calc(var(--topbar-height-h5, 62px) + 40px)) + 8px)" }} />

### 使用同一个 SAT 调用 Forward 和 Managed API

如果服务端集成需要使用同一个 SAT 调用 Forward（`/api/v1/forward/*`）和 Managed（`/api/v1/cloud/*`）API，请在置换时同时传入 `qca.access` 和 `forward.access`：

```bash
SAT_RESPONSE=$(curl --silent --show-error --location "$QODER_OPENAPI_BASE_URL/api/v1/serviceToken/exchange" \
  -H "Authorization: Bearer $QODER_SA_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "audience": "qoder",
    "scope": "qca.access forward.access",
    "ttl_seconds": 3600
  }')

export QODER_SAT="$(printf '%s' "$SAT_RESPONSE" | jq -r '.access_token')"
```

<Warning>
  同时包含 `qca.access` 和 `forward.access` 的 SAT 在 Forward 中具有当前 Service Account 所属账号下的**管理员权限**，可管理该账号下的 Forward 资源。仅应在受信任的服务端使用；请勿提供给终端用户或不受信任的客户端，并建议按环境隔离 SA Key、使用满足业务需要的最短有效期。
</Warning>

同一个 SAT 可分别调用两类 API：

```bash
# Forward API
curl -s "$QODER_API_BASE_URL/api/v1/forward/templates?limit=1" \
  -H "Authorization: Bearer $QODER_SAT"

# Managed API
curl -s "$QODER_API_BASE_URL/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_SAT"
```

<a id="compatibility-with-existing-integrations" style={{ display: "block", scrollMarginTop: "calc(max(var(--topbar-height, 112px), calc(var(--topbar-height-h5, 62px) + 40px)) + 8px)" }} />

### 兼容现有接入方式

- 仅调用 Managed API 的现有集成可继续只申请和传入 `qca.access`。
- PAT 的获取和使用方式不变。
- 仅调用 Forward API，或需要[精确吊销](/cloud-agents/api/service-account-tokens/revoke)、[绑定单个 Identity](/cloud-agents/api/service-account-tokens/create-identity)时，仍可通过 Forward Token 接口签发 SAT。

接口详情见 [ServiceAccountTokens 接口文档](/cloud-agents/api/service-account-tokens/create)。

<a id="bearer-header-format" style={{ display: "block", scrollMarginTop: "calc(max(var(--topbar-height, 112px), calc(var(--topbar-height-h5, 62px) + 40px)) + 8px)" }} />

## Bearer 头格式

使用 PAT 或 SAT 调用 Cloud Agents API 时，统一通过 Bearer 方式传递：

```text
Authorization: Bearer <PAT 或 SAT>
```

建议将当前选用的令牌设置为统一环境变量：

```bash
# 个人用户
export QODER_ACCESS_TOKEN="$QODER_PAT"

# 或 Service Account
export QODER_ACCESS_TOKEN="$QODER_SAT"
```

完整请求示例：

```bash
curl -s "$QODER_API_BASE_URL/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
```

<a id="security-recommendations" style={{ display: "block", scrollMarginTop: "calc(max(var(--topbar-height, 112px), calc(var(--topbar-height-h5, 62px) + 40px)) + 8px)" }} />

## 安全建议

- 为不同环境（开发/测试/生产）创建独立 PAT 或 SA Key
- 将 PAT 和 SA Key 存储在密钥管理系统中，不要硬编码
- 置换 SAT 时仅申请集成所需的最小 scope
- 在 SAT 过期前重新置换，并安全替换运行中的令牌
- 发现 PAT 或 SA Key 泄漏时，立即在控制台撤销或轮换