> 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 請求需由 Partner API secret 驗證。把這個秘密放在可信的後端服務裡，讓 SDK 盡可能產生簽名欄位。

> **兩種簽署協議**
>
> Agent SDK 簽名使用排序請求欄位、基於秒數的時間戳和一個 nonce。直接開發者 API 請求使用\[請求簽署]（/developer-api/request-signing）中所述的獨立流程。請勿重複使用一種有效載荷格式。

<h2 id="signing-rule">
  簽署規則
</h2>

對於 Agent SDK 請求：

1. 排除 `sign` 場。
2. 省略空值欄位。
3. 將剩餘欄位名稱依 ASCII 順序排序。
4. 像 `k=v&k2=v2`一樣加入田野。
5. 計算 HMAC-SHA256 十六進位簽名，與 `apiSecret`。

SDK 應該從它傳送的同一資料建立這個值。在簽章產生後更改已簽署欄位會導致驗證失敗。

<h2 id="sdk-managed-fields">
  SDK-管理欄位
</h2>

| 場地        | 資料來源        | 描述                 |
| --------- | ----------- | ------------------ |
| agentCode | SDK 設定      | 夥伴特工代碼。            |
| 時間戳記      | 目前伺服器時間     | Unix 的時間戳記在幾秒內。    |
| 不行        | 安全隨機值       | 重播保護隨機字串。          |
| 標誌        | HMAC-SHA256 | 請簽名。               |
| 貨幣        | 預設貨幣        | 用於轉帳/帳戶時 API 省略貨幣。 |

<h2 id="secret-storage">
  秘密儲存
</h2>

* 從後端秘密管理器或受保護的執行時設定載入 `apiSecret` 。
* 絕不要將秘密資料放在前端套件、行動應用程式、桌面客戶端、截圖或支援工單中。
* 將開發、舞台設計與製作的資格資料分開。
* 限制對需要該服務的服務與業者的存取。
* 刪除請求簽名、授權值及日誌中的秘密。
* 懷疑有暴露時撤銷並更換憑證。

<h2 id="clock-and-replay-protection">
  時鐘與重播保護
</h2>

SDK 包含`timestamp`和`nonce`以降低重播風險。保持後端時鐘同步，且不要重複使用手動製作的 nonce。若簽章驗證失敗，請先確認已設定的秘密、伺服器時間、序列化欄位及環境，然後再嘗試。

<h2 id="integration-checklist">
  整合檢查清單
</h2>

| 檢查   | 預期結果                                 |
| ---- | ------------------------------------ |
| 秘密地點 | 僅後端的秘密儲存。                            |
| 環境   | 基礎 URL 和資格屬於同一個環境。                   |
| 現場處理 | SDK 產生 `timestamp`、 `nonce`和 `sign`。 |
| 伐木   | 商業識別碼在被遮蔽時仍可見。                       |
| 旋轉   | 憑證持有人及更換流程都有文件記錄。                    |

<h2 id="related-security-docs">
  相關安全文件
</h2>

#### [Agent SDK 概述](/zh-TW/sdk/agent-sdk/overview)

檢視建議的後端整合流程。

#### [Webhook 與冪等性](/zh-TW/sdk/security/webhooks-idempotency)

驗證回撥簽名並防止重複處理。

#### [SDK 故障排除](/zh-TW/sdk/security/troubleshooting)

診斷簽名、時鐘、環境及請求問題。

<h2 id="localized-page-links">
  相關頁面
</h2>

* [請求簽署](/zh-TW/developer-api/request-signing)