获取访问凭证（Token）

接口地址： POST /api/openapi/v2/auth/token

Content-Type： application/json

接口说明： 通过 OAuth 2.1 客户端凭证模式获取访问凭证（access_token），或通过刷新令牌模式刷新已有的访问凭证。该接口是所有 OpenAPI v2 业务接口的鉴权入口，调用其他业务接口时需在请求头中携带获取到的 access_token。

请求参数

获取新 Token（grant_type = client_credentials）

参数 类型 必填 说明
client_id String 是 应用的客户端 ID，由系统分配。
client_secret String 是 应用的客户端密钥，由系统分配。
grant_type String 是 授权类型，固定传 client_credentials。

刷新 Token（grant_type = refresh_token）

参数 类型 必填 说明
client_id String 是 应用的客户端 ID，由系统分配。
client_secret String 是 应用的客户端密钥，由系统分配。
grant_type String 是 授权类型，固定传 refresh_token。
refresh_token String 是 之前获取到的刷新令牌。

CURL 示例

获取新 Token

curl --location --request POST '${host}/api/openapi/v2/auth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "client_id": "{Client Id}",
  "client_secret": "{Client Secret}",
  "grant_type": "client_credentials"
}'

刷新 Token

curl --location --request POST '${host}/api/openapi/v2/auth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "client_id": "{Client Id}",
  "client_secret": "{Client Secret}",
  "grant_type": "refresh_token",
  "refresh_token": "{Refresh Token}"
}'

返回示例

成功响应

{
  "code": 0,
  "message": "接口请求成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
    "expires_in": 7200,
    "token_type": "Bearer",
    "scope": "read write",
    "user_id": 12345
  }
}

失败响应

参数缺失或非法

{
  "code": -1,
  "message": "grant_type 必须为 client_credentials 或 refresh_token",
  "data": []
}

用户不存在

{
  "code": -1,
  "message": "用户不存在",
  "data": []
}

UC 服务异常

{
  "code": -1,
  "message": "UC 服务调用失败",
  "data": []
}

返回字段说明

字段 类型 说明
code Integer 响应状态码，0 表示成功，非 0 表示失败。
message String 响应描述信息。
data Object / Array 成功时返回 Token 数据对象，失败时返回空数组 []。

data 对象字段（成功时）：

字段 类型 说明
access_token String 用于调用业务接口的访问凭证，需在请求头中以 Authorization: Bearer {access_token} 的方式携带。
refresh_token String 用于在 access_token 过期后刷新获取新的 access_token。
expires_in Integer access_token 有效期（秒）。
token_type String 令牌类型，固定为 Bearer。
scope String 授权的权限范围。
user_id Integer 当前凭证关联的用户 ID。

错误码说明

code message 说明
0 接口请求成功 请求成功。
-1 grant_type 必须为 client_credentials 或 refresh_token grant_type 参数缺失或值不合法。
-1 用户不存在 client_id 对应的用户在系统中不存在。
-1 UC 服务调用失败 / UC 服务异常 上游认证服务异常，请稍后重试。

注意事项

  1. access_token 具有有效期，过期后需使用 refresh_token 重新获取。建议在 expires_in 到期前提前刷新，避免业务请求因 Token 过期而失败。
  2. client_id 和 client_secret 为敏感凭证，请妥善保管，不要在客户端代码中硬编码。
  3. 该接口无需携带 Authorization 请求头。
文档更新时间: 2026-10-21 11:28   作者：明志朋