艾思科蓝开放平台

签名机制

每个开放 API 请求都要携带 HMAC-SHA256 签名。下面给出完整口径与步骤。

所有开放 API 均需 HMAC-SHA256 签名。平台为机构下发共享密钥 appSecret，机构与平台各持一份，用同一密钥签名与验签。

签名步骤

  1. 01构造待签内容：method、path、timestamp、nonce、bodyHash 五段用 \n 连接。
  2. 02计算 bodyHash：POST 取原始 JSON body 字节的 SHA-256 十六进制小写；GET 用空串 SHA-256。
  3. 03用 appSecret 对待签内容做 HMAC-SHA256（计算前先把 appSecret 从 Base64 解码为密钥字节）。
  4. 04签名结果 Base64 放入 X-Signature，连同其余三个签名头一起发送。

签名请求头

每次请求携带 4 个请求头：X-App-Id（应用标识）、X-Timestamp（毫秒时间戳）、X-Nonce（一次性随机串）、X-Signature（签名值 Base64）。

名称说明
X-App-Id应用标识，平台为机构分配的 App ID。
X-Timestamp毫秒级时间戳；与服务器时间偏差须在 ±300 秒内。
X-Nonce一次性随机串，10 分钟内不可重复，用于防重放。
X-Signature对待签内容做 HMAC-SHA256（密钥为 appSecret）后的 Base64 签名值。

待签内容（5 行，\n 连接）

待签内容 = method + "\n" + path + "\n" + timestamp + "\n" + nonce + "\n" + bodyHash。method 为大写 HTTP 方法；path 为请求路径（不含域名与 query），如 /api/open/v1/tasks。

Plain
POST
/api/open/v1/tasks
1752804000000
f3a1c2…（一次性随机串）
9f86d0…（bodyHash，SHA-256 hex 小写）

bodyHash 计算

  • POST 提交（application/json）：对原始 JSON body 的 UTF-8 字节取 SHA-256 十六进制小写。计算 bodyHash 与实际发送的 body 必须逐字节一致（含空白与字段顺序），不要在签名后再改动 body。
  • GET 请求：对空字符串取 SHA-256 十六进制小写（固定为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855）。

算法与时间窗

签名算法：以 appSecret 为密钥对待签内容做 HMAC-SHA256，结果 Base64 编码放入 X-Signature。注意 appSecret 是 Base64 字符串，计算前须先 Base64 解码为 32 字节作为 HMAC 密钥。

时间窗与防重放：X-Timestamp 与服务器时间偏差须在 ±300 秒内；同一 X-Nonce 10 分钟内不可重复使用。

密钥格式：appSecret 为平台下发的 Base64 字符串（32 字节随机数）；请作为机密妥善保管，遗失只能轮换重发。