> ## 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.
# Autenticación de WebSocket
> Autentica las conexiones de WebSocket de Rhombus usando tokens de API — construye URLs de conexión, envía frames STOMP CONNECT y gestiona integraciones con la API de partner.
Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, [contáctenos](mailto:support@rhombus.com).
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](#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
1. Inicia sesión en la [consola de Rhombus](https://console.rhombussystems.com)
2. Navega a **Settings** > **API Access**
3. Haz clic en **Generate API Token**
4. 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
```text theme={null}
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`:
```text theme={null}
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.
```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
```
## 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:
```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 '{}'
```
La respuesta incluye tu `orgUuid`, que usarás para las suscripciones a tópicos.
## Ejemplo: conexión autenticada
```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")
```
## Autenticación con la API de partner
Si eres un partner de Rhombus que construye integraciones en nombre de organizaciones cliente:
1. Usa `partner-api-token` como `x-auth-scheme`
2. Incluye el `orgUuid` del cliente como header `x-auth-org`
3. Tu token de API de partner debe tener permisos para la organización destino
```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)
```
## 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](/es/websocket/connection-lifecycle)) |