OpenAPI AccessToken 调用说明

概述

AccessToken 认证适用于需要服务端对服务端调用 OpenAPI 的场景。调用方使用 appid 和 appkey 换取一个有时效的 Token，后续请求在 Header 中携带该 Token 即可。

Token 有效期：7200 秒（2 小时）

续期方式：在 Token 过期前调用刷新接口，有效期从续期时刻重置

Step 1 获取 Token

请求

POST /openapi/v2/token
Content-Type: application/json

请求体

字段	类型	必填	说明
appid	string	是	分配给调用方的应用 ID
appkey	string	是	与 appid 对应的密钥

{
  "appid": "your_appid",
  "appkey": "your_app_key"
}

成功响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "expiresIn": 7200
  }
}

失败响应示例

{
  "code": 6032,
  "msg": "无效的appid",
  "data": null
}

{
  "code": 6033,
  "msg": "appKey不匹配",
  "data": null
}

Step 2 调用业务接口

获取到 accessToken 后，在每次业务请求的 Header 中携带 access-token 字段即可，无需额外签名。

Header 格式

access-token: <你的 accessToken>

curl 示例

Step 3 续期 Token

建议在 Token 剩余有效期不足 10 分钟时主动调用续期接口，避免因 Token 过期导致请求失败。续期后有效期从当前时刻重置为 7200 秒。

请求

POST /openapi/v2/token/refresh
access-token: <当前有效的 accessToken>

成功响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "expiresIn": 7200
  }
}

注意：若 Token 已过期，续期接口同样会返回 6040 错误，此时需重新调用 Step 1 获取新 Token。

Step 4 吊销 Token（可选）

如需主动使 Token 失效（例如密钥泄露或服务下线），调用吊销接口。

请求

DELETE /openapi/v2/token
access-token: <要吊销的 accessToken>

成功响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

错误码速查

错误码	含义	处理建议
6032	无效的 appid	检查 appid 是否正确
6033	appkey 不匹配	检查 appkey 是否与 appid 对应
6039	请求缺少 Token	在 Header 中添加 `access-token`
6040	Token 无效或过期	重新调用获取 Token 接口

完整流程图（ASCII）

调用方                                    OpenAPI 服务
  │                                           │
  │  POST /openapi/v2/token                   │
  │  Body: { appid, appkey }                  │
  │ ─────────────────────────────────────────►│
  │                                           │ 校验 appid / appkey
  │  200 OK { accessToken, expiresIn: 7200 }  │
  │ ◄─────────────────────────────────────────│
  │                                           │
  │  POST /openapi/v2/some-api                │
  │  Header: access-token: <token>            │
  │ ─────────────────────────────────────────►│
  │                                           │ 验证 Token 有效性
  │  200 OK { code: 0, data: ... }            │
  │ ◄─────────────────────────────────────────│
  │                                           │
  │  （Token 剩余 < 10 分钟时）                  │
  │  POST /openapi/v2/token/refresh           │
  │  Header: access-token: <token>            │
  │ ─────────────────────────────────────────►│
  │                                           │ 重置有效期
  │  200 OK { accessToken, expiresIn: 7200 }  │
  │ ◄─────────────────────────────────────────│
  │                                           │
  │  （可选）DELETE /openapi/v2/token           │
  │  Header: access-token: <token>            │
  │ ─────────────────────────────────────────►│
  │                                           │ 吊销 Token
  │  200 OK { code: 0 }                       │
  │ ◄─────────────────────────────────────────│
  │                                           │

概述#

Step 1 获取 Token#

请求#

成功响应#

失败响应示例#

Step 2 调用业务接口#

Header 格式#

curl 示例#

Step 3 续期 Token#

请求#

成功响应#

Step 4 吊销 Token（可选）#

请求#

成功响应#

错误码速查#

完整流程图（ASCII）#

概述

Step 1 获取 Token

请求

成功响应

失败响应示例

Step 2 调用业务接口

Header 格式

curl 示例

Step 3 续期 Token

请求

成功响应

Step 4 吊销 Token（可选）

请求

成功响应

错误码速查

完整流程图（ASCII）