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.

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:

HTTP Headers

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

Connection URL Format

The examples below use the US host. EU organizations connect to wss://ws.eu.rhombussystems.com:8443/websocket instead — the parameters and protocol are identical.

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 '{}'

The response includes your 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")

const WebSocket = require("ws");

const API_TOKEN = "YOUR_API_KEY";
const url = "wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=api-token";

const ws = new WebSocket(url, {
  headers: {
    "x-auth-apikey": API_TOKEN,
  },
});

ws.on("open", () => {
  console.log("WebSocket connected");
});

import (
    "fmt"
    "log"
    "net/http"
    "time"

    "github.com/gorilla/websocket"
)

apiToken := "YOUR_API_KEY"
url := "wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=api-token"

headers := http.Header{}
headers.Set("x-auth-apikey", apiToken)

dialer := websocket.Dialer{
    HandshakeTimeout: 10 * time.Second,
}

conn, _, err := dialer.Dial(url, headers)
if err != nil {
    log.Fatal("Connection failed:", err)
}
fmt.Println("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)

Getting Started

Implementation Guides

Real-time Events

Prerequisites

Generating an API Token

Authentication Parameters

HTTP Headers

Query Parameters

Connection URL Format

Standard API Token

Partner API Token

Authentication Flow

Retrieving Your Organization UUID

Example: Authenticated Connection

Partner API Authentication

Security Best Practices

Troubleshooting

​Prerequisites

​Generating an API Token

​Authentication Parameters

​HTTP Headers

​Query Parameters

​Connection URL Format

​Standard API Token

​Partner API Token

​Authentication Flow

​Retrieving Your Organization UUID

​Example: Authenticated Connection

​Partner API Authentication

​Security Best Practices

​Troubleshooting

Prerequisites

Generating an API Token

Authentication Parameters

HTTP Headers

Query Parameters

Connection URL Format

Standard API Token

Partner API Token

Authentication Flow

Retrieving Your Organization UUID

Example: Authenticated Connection

Partner API Authentication

Security Best Practices

Troubleshooting