> ## Índice de la documentación > Consulta el índice completo de la documentación en: https://developer.rhombus.com/llms.txt > Úsalo para descubrir todas las páginas disponibles antes de seguir explorando. # Permisos y rotación de claves > Dale a cada integración de Rhombus el acceso mínimo que necesita: qué hereda cada credencial, cómo los scopes de OAuth limitan el rol de un usuario, cómo rotar claves de API, certificados y tokens de OAuth sin tiempo de inactividad, y cómo encontrar las acciones de tu integración en el registro de auditoría. > **Note**: Esta página se tradujo automáticamente. Si encuentras errores o tienes sugerencias, [escríbenos](mailto:support@rhombus.com). 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 | Credencial | Actúa con | Cambia cuando | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | Clave de API | El rol elegido al crear la clave | Editas el rol de la clave (se aplica en un máximo de 60 segundos) | | Clave de partner en una organización cliente | El rol que esa organización cliente le otorgó a tu cuenta de partner | El cliente cambia tu acceso de partner | | Access token de OAuth | El rol del usuario que autorizó la app, limitado a los [scopes](https://developer.rhombus.com/es/authentication/permissions#scopes-de-oauth) del token | Cambia el rol de ese usuario | | Clave de API creada con un token de OAuth | El rol indicado al crearla (uno que el usuario pueda asignar) | Editas el rol de la clave. Revocar la autorización de OAuth elimina la clave | | Token federado | El rol de la credencial que lo generó, en el momento de generarlo | No cambia: genera un token nuevo. Deja de funcionar cuando se revoca la credencial que lo generó | Los roles se gestionan en la consola, en [**Configuración → Roles**](https://console.rhombussystems.com/settings/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. | Scope | Pantalla de consentimiento | Cubre | | ---------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `read` | Lectura: ver cámaras, grabaciones y configuración | Las operaciones cuyo nombre empieza con `get`, `find`, `search`, `list`, `export`, `count`, `query`, `lookup`, `fetch`, `download`, `view`, `describe` o `preview`; los medios y el video en vivo; el WebSocket de eventos | | `write` | Escritura: cambiar la configuración y los datos | Todas las demás operaciones | | `physical` | Físico: desbloquear puertas y ascensores, bloqueo de emergencia, alarmas, altavoces y robots | Desbloqueos de puertas y ascensores (incluidos los desbloqueos de integraciones), bloqueo de emergencia, anulaciones de estado, relés, primer ingreso, armado y desarmado, escalamiento a alarma, reproducción en altavoces, el socket en vivo del robot y el envío de audio bidireccional | - 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](https://developer.rhombus.com/api-reference/overview) 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: ```text 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](https://developer.rhombus.com/es/oauth-authentication). ## 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: | Trabajo | Lo que necesita el rol | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | Panel de estado de los dispositivos | Acceso de solo lectura a las ubicaciones que reporta | | Desbloqueo de puertas desde una herramienta de mesa de ayuda | Control de acceso solo en las ubicaciones de esas puertas | | Exportar grabaciones para investigaciones | Acceso de solo lectura a los dispositivos más video guardado | | Canal de eventos (webhooks o WebSocket) | Acceso de solo lectura a todas las ubicaciones cuyos eventos necesita; los eventos de cualquier otra cosa no se entregan | | Generar tokens federados para un visor de cámaras | Acceso solo en vivo o de solo lectura a esas cámaras; los tokens lo heredan | - **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`](https://developer.rhombus.com/es/authentication/api-keys#rotar-una-clave) 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](https://developer.rhombus.com/es/authentication/api-keys#crear-una-clave-de-api)), 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`](https://developer.rhombus.com/es/authentication/api-keys#renovar-un-certificado), 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](https://developer.rhombus.com/es/oauth-authentication). ## 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](https://developer.rhombus.com/es/authentication/federated-tokens)). ## 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 - `. Las acciones de un partner se registran en la organización cliente. Consúltalo en la consola o con [`getAuditFeed`](https://developer.rhombus.com/api-reference/report-webservice/get-audit-feed) (la clave necesita permiso para ver reportes).