鉴权方式概述
开放平台采用「Access Key + Secret + HMAC-SHA256 签名」方式鉴权，不使用 OAuth。每个密钥归属于一个客户账号，只能访问该客户的数据。
密钥获取方式
- 登录大鹏云会员中心。
- 进入「账户设置 / API 密钥」页面。
- 点击「创建密钥」，填写密钥名称，按需勾选权限范围、填写 IP 白名单、设置过期时间。
- 创建成功后会展示一次 Access Key 与 Secret。Secret 仅明文显示这一次，关闭页面后无法再次查看，请立即保存到安全的凭据管理系统。
| 要素 | 格式 | 说明 |
|---|
| Access Key | AKID + 24 位大写十六进制 | 公开标识，可出现在请求头中，用于定位密钥记录。 |
| Secret | 64 位小写十六进制（32 字节随机数） | 绝密信息，仅用于本地计算签名，不得随请求发送。服务端只保存其 SHA-256 哈希。 |
| 权限范围 | 逗号分隔的 scope 列表，或 * | 不勾选任何范围时保存为 *（全部范围）。实际可用范围仍受接口上线情况限制。 |
| IP 白名单 | 逗号分隔的 IPv4 地址，如 203.0.113.10,198.51.100.7 | 留空表示不限制来源 IP。填写后仅白名单内的 IP 可调用。 |
| 过期时间 | 日期时间，如 2027-12-31 23:59:59 | 留空表示永不过期。到期后密钥自动失效，可重新创建。 |
安全要求：Secret 泄露等同于账号数据被读取。禁止将 Secret 写入前端 JS、App 安装包、Git 仓库或工单截图。若怀疑泄露，请立即在会员中心吊销该密钥并重新创建。
签名生成算法
服务端校验签名时使用的 HMAC 密钥是 Secret 的 SHA-256 十六进制哈希值，而不是 Secret 原文。请严格按以下四步生成：
第 1 步：准备签名密钥
signing_key = SHA256_HEX(secret) // 64 位小写十六进制字符串
第 2 步：拼接待签名字符串
payload = timestamp + "\n" + raw_body
| 组成 | 说明 |
|---|
| timestamp | 当前 Unix 时间戳（秒），必须与请求头 X-Timestamp 完全一致。服务端允许 ±300 秒误差。 |
| 换行符 | 固定为单个 \n（LF，ASCII 0x0A），前后不要添加空格。 |
| raw_body | 请求体的原始字节。GET 请求无请求体时按空字符串处理，此时 payload 为 timestamp + "\n"。 |
第 3 步：计算 HMAC
signature = HMAC_SHA256(key = signing_key, message = payload) // 输出 64 位小写十六进制
第 4 步：放入请求头
X-Access-Key: AKID8F2C4A91B7D34E6F0A1C2B3D
X-Timestamp: 1761000000
X-Signature: 4f8b2c...（64 位小写十六进制）
必须使用原始请求体签名：如果先构造 JSON、签名，再用不同方式重新序列化发送（键顺序变化、空格变化、中文被转义），服务端会对不上签名。请坚持「先序列化为最终字节 → 对这段字节签名 → 原样发送这段字节」。
| 易错点 | 正确做法 |
|---|
| 用 Secret 原文做 HMAC 密钥 | 必须先用 SHA-256 计算 Secret 的十六进制哈希，再作为 HMAC 密钥。 |
| 用发送前的时间重新取时间戳 | 签名使用的 timestamp 必须与 X-Timestamp 一模一样。 |
| GET 请求漏签名空 body | GET 无 body 时，payload 仍为 timestamp + "\n"，不可省略换行符。 |
| 签名大写十六进制 | 统一使用小写十六进制；服务端按字符串精确比较。 |
请求头规范
| 请求头 | 必填 | 说明 |
|---|
| X-Access-Key | 是 | Access Key，用于定位密钥记录。 |
| X-Timestamp | 是 | Unix 时间戳（秒），与签名使用的值一致，允许 ±300 秒偏差。 |
| X-Signature | 是 | HMAC-SHA256 签名结果，64 位小写十六进制。 |
| Content-Type | 写请求必填 | 推荐 application/json; charset=utf-8；也可使用 application/x-www-form-urlencoded。 |
| Accept | 否 | 固定返回 JSON，无需特殊设置。 |
服务端会依次校验：三个请求头是否齐全 → 时间戳窗口 → 密钥是否存在 → 密钥状态与有效期 → IP 白名单 → 签名 → 限流 → 权限范围（scope）。任一步失败即返回对应错误码，不会进入业务处理。
鉴权失败处理
| HTTP | error.code | 典型 message | 处理建议 |
|---|
| 401 | missing_headers | Missing required headers: X-Access-Key / X-Timestamp / X-Signature | 补齐三个请求头后重试。 |
| 401 | auth_failed | 请求已过期（时间戳不在 ±5 分钟窗口内） | 校准服务器时间（建议启用 NTP），重新生成时间戳与签名。 |
| 401 | auth_failed | Access Key 不存在 / 签名验证失败 | 核对 Access Key 与 Secret 是否属于同一密钥；核对签名密钥是否为 Secret 的 SHA-256。 |
| 403 | auth_failed | 密钥已禁用或已过期 | 在会员中心查看密钥状态，必要时重新创建。 |
| 403 | auth_failed | 当前 IP 不在白名单内 | 将出口公网 IP 加入白名单，或清空白名单改为不限。 |
| 403 | forbidden_scope | This API key does not have permission to call order.create | 在会员中心为该密钥勾选对应权限范围（或改为全部范围）。 |
说明：鉴权类失败的 error.code 统一为 auth_failed，具体原因体现在 message 中；HTTP 状态码用于区分「身份未通过」（401）与「身份已识别但无权访问」（403）。
