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 la clave sea aceptada, hasta que caduque. Esta página muestra cómo mantener pequeño el daño de una clave filtrada. Cómo crear claves y llamar a la API se explica en Autenticación.
Las claves se gestionan en API Keys en la parte Developer del menú (Admin; rotar requiere el rol Owner).
Lo que una clave nunca puede hacer
Estos límites se aplican a todas las claves, marques lo que marques:
- 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 del propietario, 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 tu 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. Concede solo los permisos necesarios
En New API Key, elige Module permissions un módulo cada vez. Cada módulo ofrece un preajuste Read only. Integraciones típicas:
| Integración | Permisos |
|---|---|
| Una herramienta de informes que lee dispositivos e histórico | Read only en dispositivos y telemetría |
| Un ERP que escribe límites en los dispositivos | Lectura de dispositivos, escritura de atributos |
| Un sistema de tickets que reconoce alarmas | Lectura y reconocimiento de alarmas |
Evita una clave para todo. Una clave por integración deja claro qué expone una filtración y permite revocar una integración sin detener las demás.
Los ámbitos 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 anteriores son lo que necesita la mayoría de las integraciones.»
2. Vincula 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, así que un atacante no obtiene información.
Tu organización puede definir un valor predeterminado para las claves sin lista propia: API Key Settings > Tenant Subnet Allowlist.
3. Haz que caduque
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:
| Ajuste | Predeterminado | Uso |
|---|---|---|
| Maximum Key Lifetime (days) | 0 (el límite de 365 días) | Redúcelo para forzar vidas más cortas. También reduce el valor predeterminado. |
| Require Expiry on Every Key | Desactivado | Las llamadas a la API que crean claves deben indicar una fecha de caducidad. |
| Max Active Keys | 0 (ilimitado) | Limita cuántas claves pueden estar activas a la vez. |
| Per-Key Rate Limit (requests/minute) | 0 (el 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. Decide quién es 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»). Marca como claves de servicio las de las integraciones de producción y anota quién es responsable de cada una.
5. Rota periódicamente
Rotate key crea una clave sucesora: «Crea una clave sucesora que hereda los ámbitos y el entorno de esta clave. Durante el periodo de gracia ambas claves siguen funcionando para que puedas cambiar sin interrupción.» Define la Grace window (days); 0 revoca la clave antigua de inmediato. La tarjeta Rotation history enlaza predecesora y sucesora.
- Rota y copia el nuevo secreto («Clave rotada. Copia ahora el nuevo secreto.»).
- Pon la nueva clave en la integración.
- Comprueba que Last used y Last used IP de la clave antigua dejan de cambiar.
- Espera a que termine el periodo de gracia, o revoca la clave antigua.
6. Revoca de inmediato si tienes 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á quieras recuperar; Activate la reactiva.
- En un incidente, un propietario puede revocar varias o todas las claves a la vez.
7. Vigila las claves
| Señal | Dónde |
|---|---|
| Last used, Last used IP, Total verifications | La página de la clave |
| Una clave inactiva que de pronto se usa desde una dirección nueva | Un evento de auditoría (api_key.anomaly.detected) |
| Verificaciones fallidas | Eventos de auditoría (api_key.verify.failed) |
| Creación, rotación, eliminación, cambios de permisos | El registro de auditoría (api_key.created, api_key.rotated, api_key.deleted) |
| Abuso | El cortafuegos de IA registra incidentes sobre claves. Sus acciones para limitar o desactivar una clave están In development. 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: ábrelas una a una y concede solo los permisos de módulo que necesiten.
Almacenamiento de claves
- Guarda las claves en el almacén de secretos de tu integración, nunca en código fuente, URLs ni tickets.
- Usa claves
testpara los sistemas de prueba, para que no se confundan con claves de producción. - Si una clave se filtró, revócala primero y después averigua desde dónde se usó en el registro de auditoría.