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.
WebSocket authentication is session-based, not purely stateless. You first authenticate over HTTP with your API token to establish an authenticated session, and the WebSocket handshake reuses that session. The handshake requires an existing authenticated session and is rejected if none exists. In practice, sending the standard x-auth-apikey header (with x-auth-scheme) on the handshake request establishes and reuses that session in a single step — see Authentication flow below. 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 |
x-auth-org | Target organization UUID | Only for partner API |
Query Parameters
| Parameter | Value | Required |
|---|
x-auth-scheme | api-token or partner-api-token | Yes |
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 in the x-auth-org header:
wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=partner-api-token
Authentication Flow
The handshake authenticates over HTTP and relies on an authenticated session. Sending the x-auth-apikey header (with x-auth-scheme) on the handshake request authenticates that request, establishing the session the handshake reuses. The server rejects the handshake if no authenticated session is present.
1. Build WebSocket URL with query parameters
│
▼
2. Set HTTP headers (x-auth-apikey) to authenticate the request
│
▼
3. Initiate WebSocket handshake (WSS on port 8443)
│
▼
4. Server authenticates the HTTP request and requires an
authenticated session for the handshake
│
┌────┴────┐
▼ ▼
Session No session
present (handshake rejected,
│ 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_KEY" \
-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_KEY"
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 header
- Your partner API token must have permissions for the target organization
url = (
"wss://ws.rhombussystems.com:8443/websocket"
"?x-auth-scheme=partner-api-token"
)
headers = {
"x-auth-apikey": partner_api_token,
"x-auth-org": client_org_uuid,
}
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, or no authenticated session for the handshake | Regenerate the token in the Rhombus console and ensure the x-auth-apikey header is sent on the handshake request so a session is established |
| 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) |
