Permisos y rotación de claves

Cada credencial de Rhombus actúa con un rol: el rol de la clave de API, el rol del usuario que inició sesión en el caso de un token de OAuth (limitado por los scopes del token), o el rol de la credencial que lo generó en el caso de un token federado. El rol decide qué ubicaciones y dispositivos puede ver una solicitud y qué funciones puede usar. Dale a cada integración su propia credencial con el rol más restringido que funcione.

Qué puede hacer cada credencial

Los roles se gestionan en la consola, en Configuración → Roles. Un rol combina el acceso a ubicaciones y dispositivos (administrador, solo lectura, solo en vivo o ninguno) con permisos de funciones como control de acceso, monitoreo de alarmas, video guardado y administración de la API.

Scopes de OAuth

Una app de OAuth pide scopes cuando el usuario inicia sesión, y el usuario los ve en la pantalla de consentimiento. Un token solo puede hacer lo que permiten tanto el rol del usuario como los scopes del token: el permiso efectivo es la intersección del rol y los scopes. Un scope nunca otorga algo que el rol no permite.

• Las apps piden los scopes separados por espacios en el parámetro scope de /oauth/authorize (scope=read write). Los valores desconocidos se ignoran, y una app que no pide ningún scope recibe los tres.
• El campo scope de la respuesta del token indica lo que se otorgó, y los documentos de descubrimiento y de recurso protegido indican scopes_supported.
• Crear, rotar o renovar claves de API con un token de OAuth requiere los tres scopes.
• La Referencia de la API muestra el scope que necesita cada operación.

Una solicitud fuera de los scopes del token devuelve 403 PERMISSION_REQUIRED con un encabezado que indica el scope que falta:

WWW-Authenticate: Bearer error="insufficient_scope", scope="physical"

Un token de OAuth sin read se rechaza en el handshake del WebSocket de eventos. El audio bidireccional se verifica en cada mensaje: enviar audio sin physical cierra el socket con el código 1008.

Cómo pedir scopes en el flujo de inicio de sesión se explica en Iniciar sesión con Rhombus.

Privilegio mínimo

• Una clave por integración. El nombre de una clave aparece en el registro de auditoría, y puedes rotar o eliminar la clave de una integración sin tocar las demás.
• Un rol por trabajo, no una sola clave con muchos privilegios para todo:

• Pide solo los scopes de OAuth que necesitas. Un panel solo necesita read. Omite physical a menos que la app desbloquee puertas, controle alarmas o maneje robots.
• Dale un vencimiento a las claves. Una clave con expiresAtMs deja de funcionar por sí sola si se olvida; las claves creadas por otra clave de API siempre tienen uno.
• Las claves creadas antes de que los roles fueran obligatorios pueden no tener rol, lo que significa acceso completo a la organización. Reemplázalas por claves con un rol explícito.
• Las acciones físicas (desbloquear puertas, bloqueo de emergencia, escalamiento de alarmas) merecen su propia clave, o el scope physical solo en la app de OAuth que lo necesita, y, para cualquier cosa automatizada o impulsada por IA, un paso de aprobación humana en tu aplicación.

Rotar una clave de API

Rota las claves según tu propio calendario, antes de que venzan y siempre que una pueda haberse filtrado. rotateApiToken emite un reemplazo con el mismo rol y mantiene la clave anterior funcionando durante el período de superposición que elijas:

1. Llama a POST /api/integrations/org/rotateApiToken (claves de partner: POST /api/partner/rotateApiToken) con el tokenUuid de la clave anterior y un overlapSec suficiente para el despliegue: un día de forma predeterminada, 30 días como máximo. Para una clave de certificado, envía también una csr nueva.
2. Despliega la nueva apiKey (y el cert, en el caso de una clave de certificado) en todos los lugares que usan la clave anterior.
3. Confirma que la integración funciona con la clave nueva antes de previousKeyExpiresAtMs.
4. En previousKeyExpiresAtMs, la clave anterior deja de funcionar. Para terminarla antes, elimínala.

En la consola, el mismo resultado lleva cuatro pasos: crea una clave nueva con el mismo rol (Claves de API y certificados), despliégala, confirma que funciona y luego elimina la clave anterior.

Si una clave pudo haberse filtrado, crea su reemplazo y elimina la clave filtrada de inmediato, en lugar de esperar un período de superposición. La eliminación surte efecto en un máximo de 60 segundos en todos los hosts, y los WebSockets de eventos y de medios abiertos que usaban la clave se cierran.

Claves de certificado: los certificados duran 365 días. Conserva la clave y obtén un certificado nuevo con renewApiTokenCert, o rota la clave con una CSR nueva para reemplazar ambos.

Tokens de OAuth

• Los access tokens duran una hora. Renuévalos con el refresh token en https://auth-web.rhombussystems.com/oauth/token (grant_type=refresh_token). Los clientes confidenciales envían su client ID y su client secret; los clientes públicos (solo PKCE, token_endpoint_auth_method none) envían solo client_id.
• Cada renovación devuelve un refresh token nuevo, y el anterior deja de funcionar, así que guarda el nuevo cada vez. Presentar un refresh token ya reemplazado dentro de los 30 segundos se rechaza; después de 30 segundos, revoca toda la autorización, incluidas las claves de API creadas con ella.
• Un refresh token que no se usa durante 90 días vence. Una renovación fallida devuelve 400 invalid_grant; vuelve a llevar al usuario por el inicio de sesión.
• Revoca una autorización enviando el refresh token por POST a https://auth-web.rhombussystems.com/oauth/token/revoke (token y client_id codificados como formulario, más client_secret para los clientes confidenciales). Sus access tokens dejan de funcionar en un máximo de 60 segundos, las claves de API que la app creó con ella se eliminan y los tokens federados generados con ella dejan de funcionar. Eliminar una app de OAuth revoca todas sus autorizaciones.

Las organizaciones de la UE usan auth-web.eu.rhombussystems.com. Consulta Iniciar sesión con Rhombus.

Tokens federados

Los tokens federados dejan de funcionar cuando se agota su durationSec: una hora de forma predeterminada, 24 horas como máximo. Un token deja de funcionar antes si lo revocas con POST /api/org/revokeFederatedSessionToken, o si se revoca la credencial que lo generó: se elimina la clave de API, se revoca la autorización de OAuth o termina la sesión de la app móvil. Mantenlos cortos y limitados a un dispositivo (Tokens federados).

Registro de auditoría

Las acciones realizadas con una clave de API (cambios, desbloqueos, exportaciones) quedan registradas en el registro de auditoría de la organización con el nombre de la clave, que aparece como API - <key name>. Las acciones de un partner se registran en la organización cliente. Consúltalo en la consola o con getAuditFeed (la clave necesita permiso para ver reportes).