Autenticación de WebSocket

Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, contáctenos.

Todas las conexiones de WebSocket a la plataforma Rhombus requieren autenticación con token de API. Esta página explica cómo obtener un token, construir la URL de conexión y gestionar la autenticación tanto para integraciones estándar como de partner.

La autenticación de WebSocket está basada en sesión, no es puramente sin estado. Primero te autenticas sobre HTTP con tu token de API para establecer una sesión autenticada, y el handshake del WebSocket reutiliza esa sesión. El handshake requiere una sesión autenticada existente y se rechaza si no existe ninguna. En la práctica, enviar el header estándar x-auth-apikey (junto con x-auth-scheme) en la solicitud de handshake establece y reutiliza esa sesión en un solo paso — consulta Flujo de autenticación más abajo.

Requisitos previos

Una organización de Rhombus con acceso a la API habilitado
Un token de API generado desde la consola de Rhombus

Las conexiones de WebSocket no admiten autenticación basada en certificados (mTLS). Si tu integración con la API REST usa certificados, debes generar un token de API separado para WebSocket.

Generar un token de API

Inicia sesión en la consola de Rhombus
Navega a Settings > API Access
Haz clic en Generate API Token
Copia y almacena el token de forma segura

Parámetros de autenticación

La autenticación de WebSocket requiere tanto headers HTTP como parámetros de query durante el handshake:

Headers HTTP

Header	Valor	Requerido
`x-auth-apikey`	Tu token de API	Sí
`x-auth-org`	UUID de la organización destino	Solo para la API de partner

Parámetros de query

Parámetro	Valor	Requerido
`x-auth-scheme`	`api-token` o `partner-api-token`	Sí

Formato de la URL de conexión

Token de API estándar

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

Token de API de partner

Las integraciones de partner pueden operar en nombre de organizaciones cliente especificando la organización destino en el header x-auth-org:

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

Flujo de autenticación

El handshake se autentica sobre HTTP y depende de una sesión autenticada. Enviar el header x-auth-apikey (junto con x-auth-scheme) en la solicitud de handshake autentica esa solicitud, estableciendo la sesión que el handshake reutiliza. El servidor rechaza el handshake si no hay ninguna sesión autenticada presente.

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

Recuperar el UUID de tu organización

Antes de suscribirte a tópicos, necesitas el UUID de tu organización. Recupéralo mediante la API REST:

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

La respuesta incluye tu orgUuid, que usarás para las suscripciones a tópicos.

Ejemplo: conexión autenticada

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

Autenticación con la API de partner

Si eres un partner de Rhombus que construye integraciones en nombre de organizaciones cliente:

Usa partner-api-token como x-auth-scheme
Incluye el orgUuid del cliente como header x-auth-org
Tu token de API de partner debe tener permisos para la organización destino

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)

Buenas prácticas de seguridad

Nunca incluyas tokens de API directamente en el código fuente. Usa variables de entorno o un gestor de secretos.
Rota los tokens regularmente y revoca los tokens no utilizados desde la consola de Rhombus.
Usa solo WSS. El endpoint de Rhombus aplica cifrado TLS en el puerto 8443.
Almacena los tokens de WebSocket por separado si tu aplicación también usa autenticación basada en certificados para la API REST.

Solución de problemas

Error	Causa	Solución
HTTP 401	Token de API inválido o expirado, o ninguna sesión autenticada para el handshake	Regenera el token en la consola de Rhombus y asegúrate de que el header `x-auth-apikey` se envíe en la solicitud de handshake para que se establezca una sesión
HTTP 403	El token carece de los permisos requeridos	Verifica los alcances del token y el acceso a la organización
Tiempo de espera de conexión agotado	Problema de red o firewall	Asegúrate de que el acceso saliente al puerto 8443 esté permitido
No se recibe el frame STOMP CONNECTED	La autenticación tuvo éxito pero el handshake STOMP falló	Verifica el formato del frame STOMP CONNECT (consulta Ciclo de vida de la conexión)

Comenzar

Guías de implementación

Eventos en tiempo real

Requisitos previos

Generar un token de API

Parámetros de autenticación

Headers HTTP

Parámetros de query

Formato de la URL de conexión

Token de API estándar

Token de API de partner

Flujo de autenticación

Recuperar el UUID de tu organización

Ejemplo: conexión autenticada

Autenticación con la API de partner

Buenas prácticas de seguridad

Solución de problemas

​Requisitos previos

​Generar un token de API

​Parámetros de autenticación

​Headers HTTP

​Parámetros de query

​Formato de la URL de conexión

​Token de API estándar

​Token de API de partner

​Flujo de autenticación

​Recuperar el UUID de tu organización

​Ejemplo: conexión autenticada

​Autenticación con la API de partner

​Buenas prácticas de seguridad

​Solución de problemas

Requisitos previos

Generar un token de API

Parámetros de autenticación

Headers HTTP

Parámetros de query

Formato de la URL de conexión

Token de API estándar

Token de API de partner

Flujo de autenticación

Recuperar el UUID de tu organización

Ejemplo: conexión autenticada

Autenticación con la API de partner

Buenas prácticas de seguridad

Solución de problemas