> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trae.cn/llms.txt
> 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=3024x1713](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4642c5fc119a4af7b0c7e4d7915a111f~tplv-goo7wpa0wc-image.image)
4. 配置以下字段：
   <!-- @cols-width: 100,577 -->
   | | | \
   |**字段** |**描述** |
   |---|---|
   | | | \
   |名称 |该应用凭据的名称，不超过 30 个字符。 |
   | | | \
   |有效期 |该应用凭据的有效期。可选项：1 天、7 天、30 天、180 天、360 天、永不过期。 |
   | | | \
   |可调用 API |该应用凭据支持的权限。可选项： |\
   | | |\
   | |* **人员管理（`users`）**：全部成员管理相关的操作，包括查询、邀请和移除。 |\
   | |* **查询人员（`users:read`）**：获取企业当前的成员列表。 |\
   | |* **邀请人员（`users:write`）**：邀请新成员加入企业。 |\
   | |* **移除人员（`users:delete`）**：将成员从企业中移除。 |\
   | |* **数据分析（`statistics`）**：全部数据分析相关的操作。 |\
   | |* **日志（`audit`）**：全部日志相关的操作。 |

5. 点击 **创建** 按钮。
   界面上出现 **应用凭据创建成功** 弹窗。
6. 复制应用 ID 和应用密钥。
   :::tip 提示
   务必在此处复制应用凭据信息。凭据信息仅显示一次，关闭弹窗后将无法查看。复制后，请妥善保管信息。
   :::
   ![Image=3024x1715](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/5d79ccc8b24d4c9fa3e42cbfe6057208~tplv-goo7wpa0wc-image.image)

## 获取访问令牌 {#a3a188d4}
所有接口使用 Bearer Token 进行鉴权。调用接口前需先获取访问令牌。
```HTTP
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
{
  "access_token": "t-xxx",
  "expire": 7200,
  "token_type": "Bearer"
}
```

<!-- @cols-width: 244,244,366 -->
| | | | \
|**参数** |**类型** |**描述** |
|---|---|---|
| | | | \
|`access_token` |string |访问令牌，用于后续 API 调用。 |
| | | | \
|`expire` |int |过期时间（秒），默认为 7200 秒（2 小时）。 |
| | | | \
|`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",
  "data": null
}
```

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