获取 accessToken

获取业务接口使用的 Bearer 令牌。每次获取成功都会撤销该租户之前的令牌。

请求

POST /open/v1/auth/token HTTP/1.1
X-App-Id: YOUR_APP_ID
X-Timestamp: CURRENT_UNIX_SECONDS
X-Sign: LOWERCASE_HMAC_SHA256
Content-Length: 0

请求头	类型	必填	说明
X-App-Id	string	是	正整数十进制字符串，不带前导零或正号
X-Timestamp	string	是	秒级 Unix 时间戳；允许服务端时间前后 300 秒
X-Sign	string	是	64 位小写十六进制 HMAC-SHA256 签名，见下方公式

三个认证请求头均必须只出现一次。

Query、请求体、Authorization 必须为空。 不提交 appSecret 字段，不发送 {}、null 或换行，不带末尾空的 ?。不使用 Idempotency-Key。

本接口签名

沿用统一七行 HMAC-SHA256 规则。方法为 POST，路径为 /open/v1/auth/token，token 和查询串为空，请求体摘要为 SHA-256 空字节摘要。不要使用省略方法和路径的签名公式。

可运行示例

设置好服务端环境变量后，下面代码获取令牌并输出有效期。运行结果中的令牌由你自己的令牌管理模块接收并保存。

Node.js

import { Client } from './client.mjs';

const client = new Client(
  process.env.GUIJI_BASE_URL,
  process.env.GUIJI_APP_ID,
  process.env.GUIJI_APP_SECRET
);
const issued = await client.issueToken();
// 把 issued.access_token 和实际过期时间保存在共享缓存中。
console.log({
  token_type: issued.token_type,
  expires_in: issued.expires_in,
  expires_at: issued.expires_at
});

Python

import os
from client import Client

client = Client(
    os.environ["GUIJI_BASE_URL"],
    os.environ["GUIJI_APP_ID"],
    os.environ["GUIJI_APP_SECRET"],
)
issued = client.issue_token()
# 把 issued["access_token"] 和实际过期时间保存在共享缓存中。
print({
    "token_type": issued["token_type"],
    "expires_in": issued["expires_in"],
    "expires_at": issued["expires_at"],
})

下载所需的 client.mjs / client.py。客户端实际发送长度为 0 的请求体，并明确拒绝 HTTP 重定向。

成功响应

HTTP 200：

{
  "code": 0,
  "message": "",
  "data": {
    "access_token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "token_type": "Bearer",
    "expires_in": 7200,
    "expires_at": "2026-09-08T10:00:00Z"
  }
}

data 字段	类型	说明
access_token	string	当前令牌，编码为不带填充的 Base64URL 字符串
token_type	string	固定为 Bearer
expires_in	integer	本次剩余有效秒数，通常为 7200；不能超过租户剩余有效期
expires_at	string	UTC 过期时间，RFC 3339 格式

响应包含 Cache-Control: no-store 和 Pragma: no-cache。不要让公共代理缓存此响应。

重复请求与限频

同一时间窗口内，可以重复使用相同的 appID、timestamp 和 sign 请求本接口；每次成功请求都会生成新令牌，撤销旧令牌。当前协议不使用请求 nonce。

• 同一 IP：60 次 / 300 秒。
• 同一 appID：20 次 / 300 秒。
• 超出时返回 HTTP 429，并携带 Retry-After。

这不是“每次业务调用前都要获取”的接口。多实例系统应共享一个当前令牌，由单一刷新流程维护。

常见错误

HTTP	原因
400	认证头缺失/重复、格式不合法；请求体、query 或 Authorization 不为空
401	签名错误、appID 不存在，或签名时间超出允许窗口
403	租户停用、删除或到期
429	获取令牌过频
503	服务请求并发已满

完整处理方式见错误码与排查。

离线固定向量

appID    = 9001000001
appSecret= DemoSecret20260908OnlyAbc123456789
timestamp= 1788832800
sign     = 83b1946bee08f97228d31bbe5b33a38c0c52a052ebaba8a00c0b80468bd66065

以上仅用于离线验证签名算法，不是真实租户凭据，固定时间戳不能用于当前在线鉴权。

完整字段与状态

查看全部响应字段、嵌套对象及枚举 · 业务状态与处理 · 错误码排查。