文档反馈
OpenAPI 的鉴权是指对访问 API 的用户或系统进行身份验证的过程，用于确保请求者身份的真实性。本文介绍 TRAE 企业版的 API 鉴权方式。
创建应用凭据
在 TRAE 企业版控制台中创建应用凭据，从而获取应用 ID（app_id）和应用密钥（app_secret），用于后续获取访问令牌。
- 登录 TRAE 企业版控制台。
- 前往 企业配置 > 开放平台。
- 在 应用凭据 页签中，点击右上角的 创建应用凭据 按钮。
界面上出现 创建应用凭据 弹窗。
- 配置以下字段：
字段
描述
名称
该应用凭据的名称，不超过 30 个字符。
有效期
该应用凭据的有效期。可选项：1 天、7 天、30 天、180 天、360 天、永不过期。
可调用 API
该应用凭据支持的权限。可选项：
- 人员管理（
users）：全部成员管理相关的操作，包括查询、邀请和移除。 - 查询人员（
users:read）：获取企业当前的成员列表。 - 邀请人员（
users:write）：邀请新成员加入企业。 - 移除人员（
users:delete）：将成员从企业中移除。 - 数据分析（
statistics）：全部数据分析相关的操作。 - 日志（
audit）：全部日志相关的操作。
- 人员管理（
- 点击 创建 按钮。
界面上出现 应用凭据创建成功 弹窗。 - 复制应用 ID 和应用密钥。
提示
务必在此处复制应用凭据信息。凭据信息仅显示一次，关闭弹窗后将无法查看。复制后，请妥善保管信息。
获取访问令牌
所有接口使用 Bearer Token 进行鉴权。调用接口前需先获取访问令牌。
请求方式：POST
请求地址：{域名}/openapi/v1/auth/token
请求体：
{
"app_id": "your_app_id",
"app_secret": "your_app_secret"
}
|
参数 |
类型 |
是否必填 |
描述 |
|---|---|---|---|
|
|
string |
是 |
应用唯一标识，在控制台创建应用后获取。 |
|
|
string |
是 |
应用密钥，在控制台创建应用后获取。 |
响应数据：
{
"access_token": "t-xxx",
"expire": 7200,
"token_type": "Bearer"
}
|
参数 |
类型 |
描述 |
|---|---|---|
|
|
string |
访问令牌，用于后续 API 调用。 |
|
|
int |
过期时间（秒），默认为 7200 秒（2 小时）。 |
|
|
string |
访问令牌类型，固定为 |
最佳实践
- 当前访问令牌的剩余有效期小于 30 分钟时，你可以重新获取新令牌。
- 建议在访问令牌过期前 5 分钟主动刷新令牌，以避免请求失败。
使用访问令牌调用 API
获取访问令牌后，在后续所有 API 请求中通过 Authorization 请求头携带：
请求头参数：
|
Header 参数 |
是否必填 |
描述 |
|---|---|---|
|
|
是 |
固定取值为 |
|
|
是 |
固定取值为 |
示例：
curl -X GET "https://{domain}/openapi/v1/users" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json"
访问令牌过期处理
当访问令牌过期时，API 会返回错误码 1002：
{
"code": 1002,
"message": "access token expired",
"data": null
}
此时需要重新调用 /openapi/v1/auth/token 获取新的访问令牌。