> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.6mm.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server.

# Agent SDK 密钥与 HMAC 签名

Agent SDK 请求使用合作方 API Secret 进行身份验证。密钥必须保存在可信后端服务中，并尽量由 SDK 自动生成签名字段。

> **两套签名协议**
>
> Agent SDK 签名使用排序后的请求字段、秒级时间戳和 nonce。直接调用 Developer API 时使用[请求签名](/zh-CN/developer-api/request-signing)中说明的另一套流程，不能混用两种签名内容格式。

<h2 id="signing-rule">
  签名规则
</h2>

Agent SDK 请求的签名步骤：

1. 排除 `sign` 字段。
2. 忽略值为空的字段。
3. 按字段名 ASCII 升序排列。
4. 拼接为 `k=v&k2=v2`。
5. 使用 `apiSecret` 计算 HMAC-SHA256 十六进制签名。

SDK 应使用与实际发送内容完全相同的数据生成签名。签名生成后再修改任何已签字段，都会导致验证失败。

<h2 id="sdk-managed-fields">
  SDK 自动处理字段
</h2>

| 字段        | 来源          | 说明              |
| --------- | ----------- | --------------- |
| agentCode | SDK 配置      | 代理商编码。          |
| timestamp | 当前服务器时间     | Unix 秒级时间戳。     |
| nonce     | 安全随机值       | 防重放随机串。         |
| sign      | HMAC-SHA256 | 请求签名。           |
| currency  | 默认币种        | 划转和账户接口未传币种时使用。 |

<h2 id="secret-storage">
  密钥存储
</h2>

* 从后端密钥管理系统或受保护的运行配置读取 `apiSecret`。
* 不要把密钥放入前端代码包、移动端、桌面客户端、截图或支持工单。
* 分离开发、测试和生产环境的凭证。
* 只允许确实需要的服务和操作人员访问。
* 从日志中移除请求签名、鉴权信息和密钥。
* 怀疑密钥泄露时立即撤销并更换。

<h2 id="clock-and-replay-protection">
  时间与防重放
</h2>

SDK 使用 `timestamp` 和 `nonce` 降低重放风险。后端时钟应保持同步，不要重复使用手动构造的 nonce。签名失败时，先检查密钥、服务器时间、序列化字段和环境是否一致，再决定是否重试。

<h2 id="integration-checklist">
  接入检查
</h2>

| 检查项  | 预期结果                                   |
| ---- | -------------------------------------- |
| 密钥位置 | 只存放在后端密钥系统中。                           |
| 环境   | Base URL 和凭证属于同一环境。                    |
| 字段处理 | 由 SDK 生成 `timestamp`、`nonce` 和 `sign`。 |
| 日志   | 保留业务 ID，同时移除凭证。                        |
| 轮换   | 已记录凭证负责人和更换流程。                         |

<h2 id="related-security-docs">
  相关安全文档
</h2>

#### [Agent SDK 概览](/zh-CN/sdk/agent-sdk/overview)

查看推荐的后端接入流程。

#### [Webhook 与幂等](/zh-CN/sdk/security/webhooks-idempotency)

验证回调签名并避免重复处理。

#### [SDK 接入排查](/zh-CN/sdk/security/troubleshooting)

排查签名、时间、环境和请求问题。