Agent SDK 密钥与 HMAC 签名
Agent SDK 密钥与 HMAC 签名
保护 Agent API 凭证，并了解 SDK 如何生成带时间戳、防重放的 HMAC-SHA256 请求签名。
Agent SDK 请求使用合作方 API Secret 进行身份验证。密钥必须保存在可信后端服务中，并尽量由 SDK 自动生成签名字段。
两套签名协议
Agent SDK 签名使用排序后的请求字段、秒级时间戳和 nonce。直接调用 Developer API 时使用请求签名中说明的另一套流程，不能混用两种签名内容格式。
签名规则
Agent SDK 请求的签名步骤：
- 排除
sign字段。 - 忽略值为空的字段。
- 按字段名 ASCII 升序排列。
- 拼接为
k=v&k2=v2。 - 使用
apiSecret计算 HMAC-SHA256 十六进制签名。
SDK 应使用与实际发送内容完全相同的数据生成签名。签名生成后再修改任何已签字段，都会导致验证失败。
SDK 自动处理字段
密钥存储
- 从后端密钥管理系统或受保护的运行配置读取
apiSecret。 - 不要把密钥放入前端代码包、移动端、桌面客户端、截图或支持工单。
- 分离开发、测试和生产环境的凭证。
- 只允许确实需要的服务和操作人员访问。
- 从日志中移除请求签名、鉴权信息和密钥。
- 怀疑密钥泄露时立即撤销并更换。
时间与防重放
SDK 使用 timestamp 和 nonce 降低重放风险。后端时钟应保持同步，不要重复使用手动构造的 nonce。签名失败时，先检查密钥、服务器时间、序列化字段和环境是否一致，再决定是否重试。