WebSocket Authentication
All WebSocket connections to the Rhombus platform require API token authentication. This page explains how to obtain a token, construct the connection URL, and handle authentication for both standard and partner API integrations.
Prerequisites
- A Rhombus organization with API access enabled
- An API token generated from the Rhombus console
WebSocket connections do not support certificate-based (mTLS) authentication. If your REST API integration uses certificates, you must generate a separate API token for WebSocket.
Generating an API Token
- Log in to the Rhombus console
- Navigate to Settings > API Access
- Click Generate API Token
- Copy and securely store the token
Authentication Parameters
WebSocket authentication requires both HTTP headers and query parameters during the handshake:
| Header | Value | Required |
|---|
x-auth-apikey | Your API token | Yes |
Query Parameters
| Parameter | Value | Required |
|---|
x-auth-scheme | api-token or partner-api-token | Yes |
x-auth-org | Target organization UUID | Only for partner API |
Standard API Token
wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=api-token
Partner API Token
Partner integrations can operate on behalf of client organizations by specifying the target org:
wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=partner-api-token&x-auth-org={clientOrgUuid}
Authentication Flow
1. Build WebSocket URL with query parameters
│
▼
2. Set HTTP headers (x-auth-apikey)
│
▼
3. Initiate WebSocket handshake (WSS on port 8443)
│
▼
4. Server validates token
│
┌────┴────┐
▼ ▼
Success Failure
│ (HTTP 401/403)
▼
5. Send STOMP CONNECT frame
│
▼
6. Receive STOMP CONNECTED frame
│
▼
Connection ready
Retrieving Your Organization UUID
Before subscribing to topics, you need your organization UUID. Retrieve it via the REST API:
curl -X POST https://api2.rhombussystems.com/api/org/getOrgV2 \
-H "x-auth-apikey: YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
orgUuid which you’ll use for topic subscriptions.
Example: Authenticated Connection
import websocket
import json
API_TOKEN = "your-api-token"
ORG_UUID = "your-org-uuid"
url = "wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=api-token"
headers = {
"x-auth-apikey": API_TOKEN
}
ws = websocket.create_connection(url, header=headers)
print("WebSocket connected")
Partner API Authentication
If you are a Rhombus partner building integrations on behalf of client organizations:
- Use
partner-api-token as the x-auth-scheme
- Include the client’s
orgUuid as the x-auth-org query parameter
- Your partner API token must have permissions for the target organization
url = (
"wss://ws.rhombussystems.com:8443/websocket"
"?x-auth-scheme=partner-api-token"
f"&x-auth-org={client_org_uuid}"
)
headers = {"x-auth-apikey": partner_api_token}
ws = websocket.create_connection(url, header=headers)
Security Best Practices
- Never hardcode API tokens in source code. Use environment variables or a secrets manager.
- Rotate tokens regularly and revoke unused tokens from the Rhombus console.
- Use WSS only. The Rhombus endpoint enforces TLS encryption on port 8443.
- Store WebSocket tokens separately if your application also uses certificate-based REST API authentication.
Troubleshooting
| Error | Cause | Solution |
|---|
| HTTP 401 | Invalid or expired API token | Regenerate token in the Rhombus console |
| HTTP 403 | Token lacks required permissions | Check token scopes and organization access |
| Connection timeout | Network or firewall issue | Ensure outbound access to port 8443 is allowed |
| STOMP CONNECTED not received | Auth succeeded but STOMP handshake failed | Verify STOMP CONNECT frame format (see Connection Lifecycle) |
