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

OpenAPI 的鉴权是指对访问 API 的用户或系统进行身份验证的过程，用于确保请求者身份的真实性。本文介绍 TRAE 企业版的 API 鉴权方式。

## 创建应用凭据 {#243c3fca}

在 TRAE 企业版控制台中创建应用凭据，从而获取应用 ID（`app_id`）和应用密钥（`app_secret`），用于后续获取访问令牌。

1. 登录 [TRAE 企业版控制台](https://console.enterprise.trae.cn/)。
2. 前往 **企业配置** > **开放平台**。
3. 在 **应用凭据** 页签中，点击右上角的 **创建应用凭据** 按钮。
   ![Image=3018x1714](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/cd79870ee90341a89c4d8ecb42464d60~tplv-goo7wpa0wc-topic.webp)
   界面上出现 **创建应用凭据** 弹窗。
4. 配置以下字段：
   <!-- @cols-width: 100,577 -->
   | **字段**  | **描述**  |
   | --- | --- |
   | 名称  | 该应用凭据的名称，不超过 30 个字符。  |
   | 有效期  | 该应用凭据的有效期。可选项：1 天、7 天、30 天、180 天、360 天、永不过期。  |
   | 可调用 API  | 该应用凭据支持的权限。可选项： | \
   | | | \
   | | * **人员管理（`users`）**：全部成员管理相关的操作，包括查询、邀请和移除。 | \
   | | * **查询人员（`users:read`）**：获取企业当前的成员列表。 | \
   | | * **邀请人员（`users:write`）**：邀请新成员加入企业。 | \
   | | * **移除人员（`users:delete`）**：将成员从企业中移除。 | \
   | | * **数据分析（`statistics`）**：全部数据分析相关的操作。 | \
   | | * **查询数据分析（`statistics:read`）**：查询数据统计、用量明细和模型用量。 | \
   | | * **日志（`audit`）**：全部日志相关的操作。 | \
   | | * **查询日志（`audit:read`）**：查询 OpenAPI 调用日志和管理员操作日志。 | \
   | | * **部门管理（`departments`）**：全部部门管理相关的操作，包括查询、创建、更新和删除部门。 | \
   | | * **查询部门（`departments:read`）**：查询企业部门信息。 | \
   | | * **管理部门（`departments:write`）**：创建、更新和删除企业部门。 | \
   | | * **配额管理（`quota`）**：管理成员的用量限额，包括查询限额和设置限额。 | \
   | | * **查询配额（`quota:read`）**：查询成员的当前用量限额。 | \
   | | * **设置配额（`quota:write`）**：设置成员的用量限额。  |
5. 点击 **创建** 按钮。
   界面上出现 **应用凭据创建成功** 弹窗。
6. 复制应用 ID 和应用密钥。
   :::tip 提示
   务必在此处复制应用凭据信息。凭据信息仅显示一次，关闭弹窗后将无法查看。复制后，请妥善保管信息。
   :::   


![Image=3500x1984](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/c75b1e978c0c448abed424ea5e608d8a~tplv-goo7wpa0wc-topic.webp)

## 获取访问令牌 {#a3a188d4}

所有接口使用 Bearer Token 进行鉴权。调用接口前需先获取访问令牌。

**请求方式**：`POST`

**请求地址**：`{域名}/openapi/v1/auth/token`

**请求体：**

```JSON
{
  "app_id": "your_app_id",
  "app_secret": "your_app_secret"
}
```

<!-- @cols-width: 183,183,183,312 -->
| **参数**  | **类型**  | **是否必填**  | **描述**  |
| --- | --- | --- | --- |
| `app_id`  | string  | 是  | 应用唯一标识，在控制台创建应用后获取。  |
| `app_secret`  | string  | 是  | 应用密钥，在控制台创建应用后获取。  |

**响应数据：**

```JSON
{
  "code": 0,
  "message": "success",
  "request_id": "req_abc123xyz",
  "data": {
    "access_token": "t-xxx",
    "expire": 7200,
    "token_type": "Bearer"
  }
}
```

<!-- @cols-width: 244,244,366 -->
| **参数**  | **类型**  | **描述**  |
| --- | --- | --- |
| `data.access_token`  | string  | 访问令牌，用于后续 API 调用。  |
| `data.expire`  | int  | 过期时间（秒），默认为 7200 秒（2 小时）。  |
| `data.token_type`  | string  | 访问令牌类型，固定为 `Bearer`。  |

:::tip 最佳实践
* 当前访问令牌的剩余有效期小于 30 分钟时，你可以重新获取新令牌。
* 建议在访问令牌过期前 5 分钟主动刷新令牌，以避免请求失败。
:::

## 使用访问令牌调用 API {#5e8140a0}

获取访问令牌后，在后续所有 API 请求中通过 `Authorization` 请求头携带：

**请求头参数：**

<!-- @cols-width: 244,244,369 -->
| **Header 参数**  | **是否必填**  | **描述**  |
| --- | --- | --- |
| `Authorization`  | 是  | 固定取值为 `Bearer {access_token}`。  |
| `Content-Type`  | 是  | 固定取值为 `application/json`。  |

**示例：**

```Bash
curl -X GET "https://{domain}/openapi/v1/users" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"
```

## 访问令牌过期处理 {#8ecc14b1}

当访问令牌过期时，API 会返回错误码 `1002`：

```JSON
{
  "code": 1002,
  "message": "access token expired",
  "request_id": "req_abc123xyz",
  "data": null
}
```

此时需要重新调用 `/openapi/v1/auth/token` 获取新的访问令牌。