Websocket 認證

本文檔說明如何使用基於簽名的方法對 WebSocket API 進行認證與授權，這種方式類似於 RESTful API，但針對 WebSocket 連線的特性進行了調整。此簽名機制確保只有授權的客戶端能夠通過驗證 API Key 與 API Secret，在初始握手時建立 WebSocket 連線。

簽名產生流程

要授權 WebSocket 連線，您需要產生一個簽名訊息。流程與 REST API 簽名類似，但針對 WebSocket 進行了調整：

1. 產生時間戳記

使用當前的 Unix 時間戳（毫秒）。
範例：1699999999999

2. 組合簽名字串

由於 WebSocket 連線不使用傳統的 HTTP 方法或請求主體，簽名字串格式如下：

• HTTP 方法：固定為 CONNECT
• 路徑：WebSocket 端點的路徑部分（如 /ws/trade/v1）
• 時間戳記：第 1 步產生的 Unix 時間戳
• 请求参数：
  • 當 URL 有查詢參數， 使用 key=value 串連的查詢參數（不含 ?）。
  • 當 URL 上沒有查詢參數，則為空字串。

格式：

CONNECT|{request_path}}|{timestamp}|{query_string}

範例：CONNECT|/ws/trade/v1|1699999999999|

如果驗證程序報錯，請參閱HTTP 回傳代碼文檔下的錯誤碼章節

3. 計算簽名

使用您的 API Secret 對簽名字串進行 HMAC-SHA256 雜湊，然後將結果進行 Base64 編碼。

傳送認證資料

您可以在 WebSocket 初始握手時，透過自訂標頭傳送認證資訊（前提是您的 WebSocket 客戶端函式庫支援）：

必要標頭：

標頭	說明
X-API-Key	您的 API Key
X-API-Timestamp	用於簽名的時間戳記
X-API-Signature	計算後的簽名字串

範例

假設如下：

• WebSocket 端點：wss://api-uat.habittrade.com/ws/trade/v1
• API Key：your-api-key
• API Secret：your-api-secret
• 時間戳記：1699999999999

簽名產生：

簽名字串：  CONNECT|/ws/trade/v1|1699999999999|
簽名：      Base64(HMAC-SHA256(signature_string, your-api-secret))

傳送標頭：

X-API-Key: your-api-key
X-API-Timestamp: 1699999999999
X-API-Signature: xyz123... (Base64 編碼簽名)

---

注意事項

• 時間戳記準確性：請確保時間戳記與伺服器時間相差不超過 ±5 分鐘，否則認證會失敗。
• 安全性：伺服器會使用 API Key 與簽名驗證連線。請妥善保管您的 API Secret。

---

透過此機制，您可以使用與 REST API 相同的 API Key 與 API Secret，安全地對 WebSocket 連線進行認證。