API 认证

概述

开放平台 API 使用 AppKey + HMAC-SHA256 签名 机制进行认证，确保请求来源合法且内容未被篡改。

凭证获取

在开发者控制台「应用管理」中创建应用后，即可获取以下凭证：

凭证	说明
AppKey	应用唯一标识，用于识别调用方身份
AppSecret	应用密钥，用于签名计算，务必妥善保管，不可泄露

认证流程

① 生成时间戳（秒级）+ 随机字符串（Nonce）
      │
      ▼
② 拼接待签名串：AppKey + Timestamp + Nonce + Body
      │
      ▼
③ 使用 AppSecret 计算 HMAC-SHA256 签名，Base64 编码
      │
      ▼
④ 将 AppKey、Timestamp、Nonce、Sign 放入请求 Header
      │
      ▼
⑤ 发送请求

认证参数

每个请求必须在 HTTP Header 中携带以下认证信息：

Header	类型	必填	说明	示例
X-App-Key	String	是	应用 AppKey	app_test_001
X-Timestamp	String	是	Unix 时间戳（秒级）	1710000000
X-Nonce	String	是	随机字符串，每次请求必须唯一	a1b2c3d4e5f6
X-Sign	String	是	HMAC-SHA256 签名（Base64 编码）	7d2f8a...

签名算法详见 签名算法。

安全机制

时间戳校验

• 服务端检查时间戳与当前时间的差值
• 超过 ±5 分钟 的请求将被拒绝
• 请确保服务器时间准确（建议使用 NTP 同步）

Nonce 防重放

• 每个 Nonce 在 5 分钟内只能使用一次
• 重复使用同一 Nonce 的请求将被拒绝
• 建议使用 UUID 生成

IP 白名单

• 如果应用配置了 IP 白名单，只有白名单内的 IP 才能调用
• 详见 IP 白名单

QPS 限流

• 如果应用配置了 QPS 限制，超过限制的请求将被拒绝
• 收到 429 响应时，请降低请求频率

认证失败响应

所有认证失败的响应格式统一为：

{
  "code": <HTTP状态码>,
  "msg": "<错误描述>",
  "data": null
}

错误码一览

HTTP 状态码	错误信息	排查建议
401	缺少必要的认证头信息	检查是否携带了全部 4 个认证 Header
401	AppKey 无效	确认 AppKey 是否正确
401	时间戳格式错误	X-Timestamp 必须是数字（秒级时间戳）
401	时间戳已过期	检查服务器时钟是否准确
401	请求已被使用（Nonce 重复）	确保每次请求使用不同的 Nonce
401	签名验证失败	参照 签名算法 排查
403	应用已禁用	联系平台管理员确认应用状态
403	请求 IP 不在白名单中	在控制台添加服务器出口 IP
429	请求频率超过限制	降低请求频率或申请提升 QPS