Autenticación de WebSocket

El WebSocket de eventos (wss://ws.rhombussystems.com:8443/websocket) autentica la solicitud HTTP de upgrade (el handshake). Acepta tres credenciales:

• Una clave de API, estándar o de partner, en un encabezado de la solicitud.
• Un access token de OAuth con el scope read, como Authorization: Bearer <token>.
• Un token federado, como encabezados o parámetros de consulta. Es la que puede usar un navegador.

Las claves de certificado (mTLS) no se aceptan en esta conexión.

Requisitos previos

• Una credencial:
  • Una clave de API creada en la Consola de Rhombus con Tipo de autenticación: Token de API. Consulta Claves de API y certificados.
  • O un access token de OAuth obtenido con Iniciar sesión con Rhombus cuyo grant incluya el scope read.
  • O un token federado generado por tu backend.
• Un cliente que pueda enviar esa credencial. Las claves de API y los tokens de OAuth viajan en encabezados de la solicitud, y los navegadores no pueden definir encabezados en un handshake de WebSocket, así que una app web se conecta desde su backend y retransmite los eventos, o abre el socket en el navegador con un token federado en la URL (consulta Conectarse desde un navegador).

Generar un token de API

1. Inicia sesión en la consola de Rhombus
2. Ve a Configuración → Integraciones y recursos para desarrolladores → Tokens de API y haz clic en Agregar clave de API
3. Escribe un Nombre, establece el Tipo de autenticación en Token de API y selecciona un Rol. El rol decide qué eventos recibe la conexión (consulta Qué recibe una conexión).
4. Copia el token y guárdalo de forma segura

Parámetros de autenticación

Las credenciales van en el handshake (la solicitud HTTP de upgrade). Los valores que se envían después en el frame STOMP CONNECT (login, passcode o encabezados personalizados) se ignoran.

Las credenciales de partner usan los mismos esquemas (partner-api-token y partner-api-oauth-token siguen funcionando como alias) y agregan un encabezado:

Una clave de API o un token de OAuth enviados como parámetro de consulta no se leen, y el handshake falla con 401.

Formato de la URL de conexión

Usa el puerto 8443 y TLS 1.2 o posterior. Las credenciales están vinculadas a una región, como toda credencial de Rhombus, así que una clave o un token de la UE solo funcionan en el host de la UE. Consulta Regiones de EE. UU. y UE.

Clave de API

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

Envía la clave en el encabezado x-auth-apikey.

Access token de OAuth

wss://ws.rhombussystems.com:8443/websocket

Envía Authorization: Bearer <access token>. Un token cuyo grant no incluye el scope read se rechaza con 403 PERMISSION_REQUIRED y WWW-Authenticate: Bearer error="insufficient_scope", scope="read".

Token federado

wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=federated-token&x-auth-ft=TOKEN

El token tiene el rol de la credencial que lo generó. Si se generó con domain, el Origin del handshake debe coincidir con ese origen, o se rechaza con 403 DOMAIN_NOT_ALLOWED.

Token de API de partner

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

Envía la clave de partner en x-auth-apikey y el UUID de la organización cliente en el encabezado x-auth-org. Consulta Autenticación con la API de partner.

Flujo de autenticación

1. Arma la URL (x-auth-scheme como parámetro de consulta o encabezado)
         │
         ▼
2. Agrega la credencial: x-auth-apikey, Authorization: Bearer o x-auth-ft
   (y x-auth-org para credenciales de partner)
         │
         ▼
3. Abre el WebSocket (wss, puerto 8443)
         │
    ┌────┴─────────────────────────┐
    ▼                              ▼
 Credenciales aceptadas        Rechazo antes del upgrade:
    │                          401 (credencial ausente, desconocida,
    ▼                               expirada o revocada),
4. Envía STOMP CONNECT         403 (credencial válida, no permitida),
    │                          429 (límite de solicitudes)
    ▼
5. Recibe STOMP CONNECTED → suscríbete

No se necesita una sesión HTTP previa. La credencial se verifica en el handshake y de nuevo aproximadamente una vez por minuto mientras la conexión está abierta (consulta Revocación).

Recuperar el UUID de tu organización

Los nombres de los tópicos incluyen el UUID de tu organización. Recupéralo con la API REST:

curl -X POST https://api2.rhombussystems.com/api/org/getOrgV2 \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

El UUID de la organización está en org.uuid en la respuesta.

Ejemplo: conexión autenticada

import websocket

API_TOKEN = "YOUR_API_KEY"

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")

import websocket

ACCESS_TOKEN = "YOUR_OAUTH_ACCESS_TOKEN"  # its grant must include the read scope

url = "wss://ws.rhombussystems.com:8443/websocket"
headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}"
}

ws = websocket.create_connection(url, header=headers)
print("WebSocket connected")

// federatedToken comes from your backend; never put an API key in the page
const url = new URL("wss://ws.rhombussystems.com:8443/websocket");
url.searchParams.set("x-auth-scheme", "federated-token");
url.searchParams.set("x-auth-ft", federatedToken);

const ws = new WebSocket(url);
ws.onopen = () => console.log("WebSocket connected");

Conectarse desde un navegador

• Usa un token federado en la URL. Tu backend lo genera con generateFederatedSessionToken y se lo entrega a la página, que abre el socket con x-auth-scheme=federated-token&x-auth-ft=<token> (consulta el ejemplo de navegador de arriba). Genéralo para la sesión del usuario (durationSec vale una hora de forma predeterminada y no puede superar las 24 horas), lee expiresAtMs en la respuesta y genera uno nuevo antes de que expire. Cuando la sesión termine, revócalo con POST /api/org/revokeFederatedSessionToken, desde tu backend o desde la página, autenticándote con el propio token. Consulta Tokens federados.
• Vincula el token a tu página con domain. Un token generado con domain (un origen absoluto como https://app.example.com) solo se acepta cuando el Origin del handshake coincide con él.
• Una sesión iniciada en la consola de Rhombus solo funciona desde la consola de Rhombus. Un handshake que se apoya en las cookies de sesión de la consola solo se acepta desde un origen de la consola de Rhombus, así que una página de tu propio sitio no puede usar la sesión de consola de un usuario. Los handshakes con una clave de API, un token de OAuth, un token federado o la app móvil de Rhombus no se verifican por origen; el domain de un token federado es su propia verificación de origen.

Qué recibe una conexión

• Los eventos se filtran según el rol de la credencial. Una clave de API usa su rol. Un token de OAuth actúa con el rol del usuario que inició sesión, limitado a los scopes del token. Un token federado tiene el rol de la credencial que lo generó. Un rol de acceso completo recibe todos los eventos de la organización. Un rol limitado a algunas ubicaciones o dispositivos recibe solo los eventos de esos; el resto se descarta sin ningún error. Si una conexión no recibe nada, revisa el rol antes que cualquier otra cosa.
• Las alertas de políticas siguen la misma regla. Una alerta de política se entrega cuando el rol tiene acceso al dispositivo de la alerta o a su ubicación. Una alerta sin ninguno de los dos solo llega a roles de acceso completo.
• Los tipos de entidad sin verificación de acceso solo llegan a roles de acceso completo. Un rol limitado recibe los tipos de entidad que el servidor puede verificar contra sus dispositivos y ubicaciones, y ningún otro.
• La conexión es solo de recepción. Los clientes se suscriben; no envían comandos por ella. Usa la API REST para actuar.
• Suscribirse al tópico de otra organización se rechaza. El servidor envía un frame STOMP ERROR y cierra el socket con el código 1002.

Autenticación con la API de partner

Si eres un partner de Rhombus que recibe eventos de una organización cliente:

1. Usa tu clave de partner con el esquema api-token (partner-api-token funciona como alias)
2. Envía el orgUuid del cliente en el encabezado x-auth-org. Es obligatorio: una credencial de partner sin él se rechaza con 403 PERMISSION_REQUIRED. Un valor vacío cuenta como ausente, un parámetro de consulta no se lee y un valor que no es un UUID válido recibe 400 INVALID_AUTH_ORG.
3. Abre una conexión por organización cliente; x-auth-org es fijo durante toda la vida de la conexión

url = (
    "wss://ws.rhombussystems.com:8443/websocket"
    "?x-auth-scheme=api-token"
)
headers = {
    "x-auth-apikey": partner_api_token,
    "x-auth-org": client_org_uuid,
}

ws = websocket.create_connection(url, header=headers)

Si tu cuenta de partner no está autorizada para ese cliente, el handshake falla con 403 PARTNER_CLIENT_ACCESS_DENIED.

Revocación

Eliminar una clave, cambiar su rol, revocar un grant de OAuth o revocar un token federado (o la credencial que lo generó) surte efecto en 60 segundos o menos. Una conexión abierta que usaba esa credencial recibe un frame STOMP ERROR y se cierra con el código 1008. Después de un cambio de rol, al reconectarte se aplica el nuevo rol. Después de una eliminación o revocación, todo handshake con esa credencial falla con 401, así que no te reconectes en bucle después de un 1008: revisa primero la credencial.

Buenas prácticas de seguridad

• Mantén las claves en tu servidor. Nunca envíes una clave de API a un navegador o a una app móvil; retransmite los eventos desde tu backend, o dale al navegador un token federado de corta duración.
• Usa una credencial dedicada con el rol más restringido que aún vea los dispositivos que necesitas. Consulta Permisos y rotación de claves.
• Pide solo los scopes de OAuth que necesitas. El WebSocket de eventos necesita read.
• Reconéctate con backoff. Los handshakes cuentan para el límite de solicitudes de tu organización; un bucle de reconexión sin pausas recibe respuestas 429.

Solución de problemas

Un handshake rechazado antes del upgrade devuelve un código HTTP, un encabezado x-rhombus-txid y el mismo cuerpo JSON que todos los hosts de Rhombus (consulta Errores):

{
  "msg": "x-auth-org is required for partner credentials",
  "error": true,
  "errorCode": "PERMISSION_REQUIRED",
  "errorMsg": "Your role does not have the required permission on the requested resource.",
  "status": 403,
  "timestamp": 1791367200000,
  "txid": "6f1c2a9e4b7d"
}

Lee errorCode para conocer el motivo. Indica el txid cuando contactes a soporte.