Agent SDK秘密和HMAC簽名
保護代理 API 憑據並瞭解 SDK 如何生成帶時間戳、防重放的 HMAC-SHA256 請求籤名。
Agent SDK 請求通過合作伙伴 API 秘密進行身份驗證。將這個秘密保存在受信任的後端服務中，並讓 SDK 儘可能生成簽名字段。
兩個簽名協議
Agent SDK 簽名使用排序的請求字段、基於秒的時間戳和隨機數。直接 Developer API 請求使用中描述的單獨過程 請求籤名。不要將一種有效負載格式重複用於另一種有效負載格式。
簽名規則
對於 Agent SDK 請求：
- 排除
sign字段。 - 省略具有空值的字段。
- 按 ASCII 順序對剩餘字段名稱進行排序。
- 將字段連接為
k=v&k2=v2。 - 使用
apiSecret計算 HMAC-SHA256 十六進制簽名。
在加入簽名有效負載之前，數組值被序列化為緊湊的 JSON。例如，platformUserIds 標記為 ["1188041528"]，在 k=v 有效負載中給出 platformUserIds=["1188041528"]。保留數組元素順序、雙引號和字符串 ID；請勿插入格式空格或使用 Java List.toString()（例如 [1188041528]）。 SDK 自動處理此序列化。
SDK 應根據其發送的相同數據構建此值。簽名生成後更改簽名字段會導致驗證失敗。
SDK-管理字段
秘密儲藏室
- 從後端秘密管理器或受保護的運行時配置加載
apiSecret。 - 切勿將秘密放在前端捆綁包、移動應用程序、桌面客戶端、屏幕截圖或支持票證中。
- 將開發、登臺和生產的憑證分開保存。
- 限制對需要的服務和運營商的訪問。
- 編輯日誌中的請求籤名、授權值和機密。
- 當懷疑存在洩露時，撤銷並更換憑證。
時鐘和重放保護
SDK 包括 timestamp 和 nonce 以降低重放風險。保持後端時鐘同步，並且不要重複使用手動構建的隨機數。如果簽名驗證失敗，請在重試之前確認配置的密鑰、服務器時間、序列化字段和環境。