Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

Refuerzo de claves de API

Dé a cada integración una clave con solo los permisos que necesita, una red, una caducidad y un propietario, y cómo rotar, revocar y supervisar las claves.

Una clave de API es una contraseña para un programa. Quien la tenga puede hacer lo que la clave permite, desde cualquier lugar donde se acepte la clave, hasta que venza. Esta página explica cómo mantener pequeño el daño de una clave filtrada. Cómo crear claves y llamar a la API está en Autenticación.

Las claves se gestionan en API Keys en la sección Developer del menú (Admin; rotarlas requiere el rol Owner).

Lo que una clave nunca puede hacer

Estos límites se aplican a todas las claves, marque lo que marque:

  • Una clave nunca va más allá de lo que el miembro que la creó puede hacer ahora: «Nunca va más allá de lo que su propietario puede hacer ahora.» Si el miembro pierde un permiso, la clave también lo pierde.
  • Una clave nunca tiene permisos exclusivos de Owner, ni permisos de los módulos de identidad y acceso (inicio de sesión, cuentas, claves de API). Por tanto, una clave no puede crear ni rotar claves ni cambiar miembros.
  • El permiso de una clave solo funciona mientras su módulo esté activado para su organización.
  • Una solicitud que lleva una clave se evalúa únicamente como esa clave; una cookie del navegador en la misma solicitud se ignora.

1. Conceda solo los permisos necesarios

En New API Key, elija Module permissions un módulo cada vez. Cada módulo ofrece un preajuste Read only. Integraciones típicas:

IntegraciónPermisos
Una herramienta de informes que lee dispositivos e historialRead only en dispositivos y telemetría
Un ERP que escribe límites en dispositivosLectura de dispositivos, escritura de atributos
Un sistema de tickets que confirma alarmasLectura y confirmación de alarmas

Evite una sola clave para todo. Una clave por integración deja claro qué expone una filtración y le permite revocar una integración sin detener las demás.

Los alcances de integración (Read, Write, Admin, SCIM Read, SCIM Write) son para endpoints de máquina con su propio contrato, como el aprovisionamiento SCIM. «Los permisos de módulo indicados arriba son los que necesitan la mayoría de las integraciones.»

2. Vincule la clave a redes

IP allowlist (optional): «Una subred por línea, p. ej. 10.0.0.0/8 o 203.0.113.7/32.» Las llamadas desde cualquier otro lugar se rechazan con la misma respuesta que una clave desconocida, de modo que un atacante no obtiene información.

Su organización puede definir un valor predeterminado para las claves sin lista propia: API Key Settings > Tenant Subnet Allowlist.

3. Haga que caduquen

Todas las claves caducan: 90 días por defecto, como máximo 365 días («90 días por defecto, como máximo un año.»). En API Key Settings:

AjustePredeterminadoUso
Maximum Key Lifetime (days)0 (el límite de 365 días)Redúzcalo para forzar vidas más cortas. También reduce el valor predeterminado.
Require Expiry on Every KeyDesactivadoLas llamadas a la API que crean claves deben indicar una fecha de caducidad.
Max Active Keys0 (ilimitado)Limita cuántas claves pueden estar activas a la vez.
Per-Key Rate Limit (requests/minute)0 (el valor predeterminado de la plataforma: 1.000 por minuto)Límite de solicitudes predeterminado de cada clave. La pantalla muestra 0 como ilimitado; la plataforma aplica 1.000 por minuto.

4. Decida quién es el propietario de la clave

Una clave deja de funcionar cuando el miembro que la creó abandona la organización, a menos que esté marcada como Service key («Sí: sobrevive a su creador»). Marque como claves de servicio las de las integraciones de producción y anote quién es responsable de cada una.

5. Rote periódicamente

Rotate key crea una clave sucesora: «Crea una clave sucesora que hereda los alcances y el entorno de esta clave. Durante el periodo de gracia, ambas claves siguen funcionando para que pueda cambiar sin interrupción.» Configure Grace window (days); 0 revoca la clave antigua de inmediato. La tarjeta Rotation history enlaza la predecesora y la sucesora.

  1. Rote y copie el nuevo secreto («Clave rotada. Copie el nuevo secreto ahora.»).
  2. Coloque la nueva clave en la integración.
  3. Compruebe que Last used y Last used IP de la clave antigua dejan de cambiar.
  4. Espere a que termine el periodo de gracia o revoque la clave antigua.

6. Revoque de inmediato si tiene dudas

  • Revoke Key: «Cualquier integración que use esta clave dejará de funcionar de inmediato. Esta acción no se puede deshacer.»
  • Deactivate detiene una clave que quizá quiera recuperar; Activate la reactiva.
  • En un incidente, un Owner puede revocar varias claves o todas a la vez.

7. Supervise las claves

SeñalDónde
Last used, Last used IP, Total verificationsLa página de la clave
Una clave inactiva que de pronto se usa desde una dirección nuevaUn evento de auditoría (api_key.anomaly.detected)
Verificaciones fallidasEventos de auditoría (api_key.verify.failed)
Creación, rotación, eliminación, cambios de permisosEl registro de auditoría (api_key.created, api_key.rotated, api_key.deleted)
AbusoEl cortafuegos de IA registra incidentes sobre las claves y puede limitar o revocar una clave. Consulta El cortafuegos de IA.

La lista de claves también muestra un aviso para las claves antiguas creadas antes de los permisos por módulo: abra cada una y concédale solo los permisos de módulo que necesite.

Almacenamiento de claves

  • Guarde las claves en el almacén de secretos de su integración, nunca en código fuente, URL ni tickets.
  • Use claves test para los sistemas de prueba, para que no se confundan con claves de producción.
  • Si una clave se filtró, revóquela primero y después averigüe desde dónde se usó en el registro de auditoría.