服务端开放能力:签名规范
开放平台 App Key/Secret 的四头 HMAC-SHA256 签名规范:请求头、签名串六段拼接、常见签名错误。
更新于 2026-10-10
服务端开放能力:签名规范
本文定义服务端开放接口(/open/v1/*)的鉴权方式:四个请求头与六段式 HMAC-SHA256 签名串。
一、前置条件
向通行证管理员领取 App Key + App Secret(与 OIDC 的 client_id/secret 相互独立)。 开放能力按应用等级授权:0 级不得调用,等级越高可用接口越多(等级模型见内部文档)。
二、四个请求头
| Header | 说明 |
|---|---|
X-Ext-Key |
app_key |
X-Ext-Timestamp |
unix 秒级时间戳(±300 秒内有效) |
X-Ext-Nonce |
随机串(60 秒内不得重复) |
X-Ext-Sign |
hex(HMAC-SHA256(app_secret, 签名串)) |
三、签名串(六段,\n 连接)
METHOD\npath\nquery\nsha256hex(body)\ntimestamp\nnonce
| 段 | 规则 |
|---|---|
| METHOD | 大写,如 GET / POST |
| path | 请求路径,不含 query,如 /open/v1/internal/balance |
| query | 原始 query 字符串(a=1&b=2);POST 为空串 |
| sha256hex(body) | 请求体的 SHA256 十六进制;GET 为空串的 sha256 |
| timestamp | 与 X-Ext-Timestamp 一致 |
| nonce | 与 X-Ext-Nonce 一致 |
四、示例(Node.js)
const crypto = require('crypto');
const ts = Math.floor(Date.now() / 1000);
const nonce = crypto.randomBytes(8).toString('hex');
const query = 'user_id=1'; // GET 的 query
const bodyHash = crypto.createHash('sha256').update('').digest('hex'); // GET 空 body
const signStr = ['GET', '/open/v1/internal/balance', query, bodyHash, ts, nonce].join('\n');
const sign = crypto.createHmac('sha256', APP_SECRET).update(signStr).digest('hex');
// GET /open/v1/internal/balance?user_id=1 带上四个 X-Ext-* 头
五、常见签名错误
6106 签名不符:六段顺序错、body 哈希不是原始字节、query 没按原样拼接(不要重新编码);- 时间戳偏差:服务器时间不准(检查 NTP);
- nonce 重复:60 秒内重试要换新 nonce。