Autenticación

Cada solicitud a Rhombus lleva una credencial. Qué credenciales puede usar una solicitud, y dónde van, depende de adónde va la solicitud: la API REST, los hosts de medios y video, el WebSocket de eventos o una cámara de tu red local. Esta página relaciona cada credencial con cada destino y explica los errores de autenticación; las páginas siguientes cubren cada credencial en detalle.

Elige una credencial

Dónde funciona cada credencial

Las cámaras de tu red local aceptan solo tokens federados. Es una decisión deliberada: en la red local, cada solicitud lleva un token de corta duración que puedes limitar a la cámara que necesita, nunca una clave de larga duración. Consulta Streaming por LAN.

Hosts por destino (Regiones de EE. UU. y UE indica las variantes de la UE):

Encabezados de la solicitud

Una solicitud indica su esquema en x-auth-scheme y lleva la credencial en el encabezado que ese esquema lee:

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

curl -X POST "https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Reglas que se aplican en todas partes:

• Los nombres de los encabezados y el valor del esquema son exactos. x-auth-scheme: api-token funciona; Api-Token no.
• Authorization: Bearer lleva solo un access token de OAuth, en la API REST, los hosts de medios y el WebSocket de eventos. Un encabezado Bearer sin x-auth-scheme se interpreta como un access token de OAuth. Las claves de API nunca van en Authorization.
• Solo los tokens federados van en una URL. x-auth-scheme y x-auth-ft pueden ser parámetros de consulta; las claves de API, los access tokens de OAuth y x-auth-org se leen solo de los encabezados.
• Las credenciales están vinculadas a una región. Una clave o un token de una organización de EE. UU. no funciona en los hosts de la UE, ni al revés. El error no menciona la región. Consulta Regiones de EE. UU. y UE.
• Vigencias: una clave de API funciona hasta que la eliminas o hasta su vencimiento (expiresAtMs), si lo tiene. Los access tokens de OAuth duran una hora. Los tokens federados duran el durationSec que pidas al generarlos: una hora de forma predeterminada, 24 horas como máximo.
• La revocación surte efecto en un máximo de 60 segundos en todos los hosts. Eliminar una clave, cambiar su rol o revocar una autorización de OAuth termina su acceso, y las conexiones WebSocket abiertas que la usaban se cierran.
• Envía Content-Type: application/json en cada POST a la API REST, incluso con un cuerpo vacío ({}).

Credenciales de partner

Las claves de partner, las claves de certificado de partner y los tokens de OAuth de partner usan los mismos esquemas que las credenciales de organización. Para actuar en una organización cliente, envía el UUID de esa organización en x-auth-org:

• x-auth-org es solo un encabezado; nunca se lee de un parámetro de consulta. Significa lo mismo para claves, certificados y tokens de OAuth de partner, y un valor vacío cuenta como ausente.
• Fuera de los endpoints /api/partner/, envía siempre x-auth-org. Una solicitud de partner sin él sigue funcionando, pero la respuesta lleva Deprecation: true y Sunset: Tue, 05 Jan 2027 00:00:00 GMT, y después de esa fecha la solicitud falla. El WebSocket de eventos rechaza un handshake de partner sin x-auth-org con 403 PERMISSION_REQUIRED.
• Un valor mal formado devuelve 400 INVALID_AUTH_ORG; una organización cliente que tu cuenta de partner no gestiona devuelve 403 PARTNER_CLIENT_ACCESS_DENIED.

Consulta API para partners para listar clientes y hacer llamadas en su nombre.

Cómo interpretar los errores de autenticación

Toda respuesta de error de la API REST, los hosts de medios y los handshakes de WebSocket tiene el mismo cuerpo JSON, y también lleva el ID de la solicitud en el encabezado x-rhombus-txid:

{
  "msg": "Unauthorized",
  "error": true,
  "errorCode": "CREDENTIAL_EXPIRED",
  "errorMsg": "The supplied credential has expired.",
  "status": 401,
  "timestamp": 1792371600000,
  "txid": "yJ2kQw8LTaO1xX4hVd7mPA"
}

Decide según el estado y errorCode, muestra o registra errorMsg, e indica txid cuando contactes al soporte. El estado te dice qué parte de la solicitud corregir:

• 401: Rhombus no pudo establecer quién llama. La credencial falta, está mal formada, es desconocida, venció o fue revocada. Corrige o reemplaza la credencial.
• 403: la credencial es válida, pero no tiene permitido hacer esto. Cambia el rol, los scopes de OAuth, la organización o los límites del token; una credencial nueva del mismo tipo no sirve.

Algunas operaciones informan una acción rechazada con HTTP 200 y "error": true en el cuerpo, así que revisa el cuerpo además del estado. La página Errores tiene el catálogo completo de códigos y las reglas de reintento.

Los hosts de medios y el WebSocket de eventos tienen sus propios casos de error; consulta Medios y transmisiones y Autenticación de WebSocket.

Próximos pasos