> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket Authentication

> Authenticate Rhombus WebSocket connections using API tokens — construct connection URLs, send STOMP CONNECT frames, and handle partner API integrations.

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.

<Note>
  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](#authentication-flow) below.
</Note>

## Prerequisites

* A Rhombus organization with API access enabled
* An API token generated from the Rhombus console

<Warning>
  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.
</Warning>

## Generating an API Token

1. Log in to the [Rhombus console](https://console.rhombussystems.com)
2. Navigate to **Settings** > **API Access**
3. Click **Generate API Token**
4. 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

### Standard API Token

```text theme={null}
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:

```text theme={null}
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.

```text theme={null}
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:

```bash theme={null}
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

<CodeGroup>
  ```python Python theme={null}
  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")
  ```

  ```javascript JavaScript theme={null}
  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");
  });
  ```

  ```go Go theme={null}
  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")
  ```
</CodeGroup>

## Partner API Authentication

If you are a Rhombus partner building integrations on behalf of client organizations:

1. Use `partner-api-token` as the `x-auth-scheme`
2. Include the client's `orgUuid` as the `x-auth-org` header
3. Your partner API token must have permissions for the target organization

```python theme={null}
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](/websocket/connection-lifecycle))                                                |