Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, contáctenos. 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 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:
| Header | Valor | Requerido |
|---|
x-auth-apikey | Tu token de API | Sí |
Parámetros de query
| Parámetro | Valor | Requerido |
|---|
x-auth-scheme | api-token o partner-api-token | Sí |
x-auth-org | UUID de la organización destino | Solo para la API de partner |
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:
wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=partner-api-token&x-auth-org={clientOrgUuid}
Flujo de autenticación
1. Build WebSocket URL with query parameters
│
▼
2. Set HTTP headers (x-auth-apikey)
│
▼
3. Initiate WebSocket handshake (WSS on port 8443)
│
▼
4. Server validates token
│
┌────┴────┐
▼ ▼
Success Failure
│ (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 '{}'
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")
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 parámetro de query 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"
f"&x-auth-org={client_org_uuid}"
)
headers = {"x-auth-apikey": partner_api_token}
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 | Regenera el token en la consola de Rhombus |
| 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) |
