鉴权

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

创建应用凭据

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

1. 登录 TRAE 企业版控制台。

2. 前往 企业配置 > 开放平台。

3. 在 应用凭据 页签中，点击右上角的 创建应用凭据 按钮。
   界面上出现 创建应用凭据 弹窗。
   

4. 配置以下字段：

   字段	描述
   名称	该应用凭据的名称，不超过 30 个字符。
   有效期	该应用凭据的有效期。可选项：1 天、7 天、30 天、180 天、360 天、永不过期。
   可调用 API	该应用凭据支持的权限。可选项： 人员管理（users）：全部成员管理相关的操作，包括查询、邀请和移除。 查询人员（users:read）：获取企业当前的成员列表。 邀请人员（users:write）：邀请新成员加入企业。 移除人员（users:delete）：将成员从企业中移除。 数据分析（statistics）：全部数据分析相关的操作。 日志（audit）：全部日志相关的操作。

5. 点击 创建 按钮。
   界面上出现 应用凭据创建成功 弹窗。

6. 复制应用 ID 和应用密钥。

   提示

   务必在此处复制应用凭据信息。凭据信息仅显示一次，关闭弹窗后将无法查看。复制后，请妥善保管信息。

   

获取访问令牌

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

POST /openapi/v1/auth/token

请求体：

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

响应数据：

{
  "access_token": "t-xxx",
  "expire": 7200,
  "token_type": "Bearer"
}

使用访问令牌调用 API

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

示例：

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 获取新的访问令牌。