服务端开放能力:签名规范

开放平台 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。