Websocket Authentication

This document outlines how to authenticate and authorize access to the WebSocket API using a signature-based method, similar to the RESTful API approach, but tailored for the nature of WebSocket connections. This signature mechanism ensures that only authorized clients can establish a WebSocket connection to the server by verifying their API Key and API Secret at the time of the initial handshake.

Signature Generation Process

To authorize a WebSocket connection, you need to generate a signed message. The process is similar to REST API signing but adapted for WebSocket:

1. Generate a Timestamp

Use the current Unix timestamp in milliseconds.
Example: 1699999999999

2. Construct the Signature String

Since WebSocket connections do not use traditional HTTP methods or request bodies, the signature string follows a simplified format:

• HTTP Method: Fixed as CONNECT
• Path: The path portion of the WebSocket endpoint (e.g., /ws/trade/v1)
• Timestamp: The Unix timestamp generated in step 1
• Request parameters:
  • When the URL contains query parameters, use concatenated key=value pairs (without the ? symbol).
  • When the URL has no query parameters, use an empty string.

Format:

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

Example: CONNECT|/ws/trade/v1|1699999999999|

If an error occurs during the authentication process, please refer to the Error Codes section under the HTTP Return Codes document.

3. Calculate the Signature

Use your API Secret to compute the HMAC-SHA256 hash of the signature string, then encode the result in Base64.

Sending Authentication Data

You can send authentication information in the initial WebSocket handshake by including custom headers — if supported by your WebSocket client library:

Required Headers:

Header	Description
X-API-Key	Your API Key
X-API-Timestamp	Timestamp used in the signature
X-API-Signature	The computed signature string

Example

assume the following:

• WebSocket Endpoint: wss://api-uat.habittrade.com/ws/trade/v1
• API Key: your-api-key
• API Secret: your-api-secret
• Timestamp: 1699999999999

Signature Generation:

Signature String:  CONNECT|/ws/trade/v1|1699999999999|
Signature:         Base64(HMAC-SHA256(signature_string, your-api-secret))

Headers Sent:

X-API-Key: your-api-key
X-API-Timestamp: 1699999999999
X-API-Signature: xyz123... (Base64-encoded signature)

---

Notes

• Timestamp Accuracy: Ensure the timestamp is within ±5 minutes of the server time to avoid authentication failure.
• Security: The server verifies the connection using the API Key and signature. Keep your API Secret confidential.

---

With this mechanism, you can securely authenticate your WebSocket connections using the same API Key and API Secret as the REST API.