Autenticación

Los programas se autentican con claves de API. Una clave actúa como el miembro que la creó, limitada a los permisos que le asignes a la clave. No hay intercambio de tokens: la clave en sí es la credencial, enviada en cada llamada.

Las claves de API son gestionadas por los administradores en API Keys (en la parte Developer del menú). Crear claves requiere un plan con claves de API.

Crear una clave

1. Abre API Keys y selecciona New API Key.
2. Introduce un Name (hasta 100 caracteres) y, opcionalmente, una Description (hasta 500).
3. En Module permissions, elige lo que la clave puede hacer, un módulo a la vez. Cada módulo ofrece un ajuste predefinido Read only; también puedes marcar permisos individuales. Usa Search modules or permissions… para encontrar uno. El selector solo muestra los permisos que tienes tú: «The key can do at most what you can do. If your own rights shrink later, the key loses them too.»
4. Define Expires on. El valor por defecto es 90 días desde hoy, como máximo un año («90 days by default, at most a year.»).
5. Opcionalmente, rellena IP allowlist: una subred por línea, por ejemplo 10.0.0.0/8 o 203.0.113.7/32. Vacío significa cualquier dirección que tu organización permita.
6. Deja Integration scopes (advanced) vacío, a menos que la documentación de una integración lo pida (por ejemplo, el aprovisionamiento SCIM).
7. Selecciona Create Key y copia la clave ahora.

Si tienes autenticación de dos factores o una passkey, Hermetry te pide que la confirmes antes de crear la clave. No se puede crear una clave mientras suplantas a un miembro.

Formato de la clave

sk_live_<first 8 characters of the organisation id>_<48 random hexadecimal characters>

Las claves live pertenecen al servicio de producción, las test a instalaciones de prueba, de modo que no se puedan confundir entre sí.

Usar una clave

Envía la clave en la cabecera Authorization en cada llamada:

curl "https://<your host>/tenant/<tenantId>/api/iot/devices" \
  -H "Authorization: Bearer sk_live_…"

• Una petición con clave de API se evalúa solo como esa clave. Una cookie del navegador en la misma petición se ignora.
• Las claves solo funcionan en las rutas de tu organización (/tenant/<tenantId>/api/...). La organización de la clave debe coincidir con el tenantId de la ruta.
• Una clave nunca funciona en rutas de plataforma, de cuenta o de inicio de sesión.

Qué puede hacer una clave

En cada llamada, deben cumplirse todas estas condiciones:

1. La clave tiene el permiso que requiere la ruta.
2. El módulo del permiso está activado para tu organización.
3. El miembro que creó la clave tiene el permiso ahora: cuentan su rol, sus grupos y las políticas de acceso de tu organización.
4. El miembro sigue siendo un miembro activo y la organización está activa.

Una clave actúa con como máximo el rol Admin, incluso si la creó un Owner. Así, una clave nunca puede tener permisos exclusivos de Owner (por ejemplo, comandos directos a dispositivos, claves de firma de firmware, ajustes peligrosos de dispositivos, rotar el secreto de un webhook) ni permisos de los módulos de identidad y acceso (inicio de sesión, cuentas, claves de API, miembros, sesiones). Por tanto, una clave no puede crear ni rotar claves.

Claves de servicio

Una clave normalmente deja de funcionar cuando su creador abandona la organización. Un Owner puede abrir la clave y seleccionar Mark as service key: entonces seguirá funcionando después de que su creador se vaya («Yes: survives its creator») y actuará como el Owner que la marcó.

Redes permitidas

La lista de IP permitidas de una clave admite hasta 100 subredes en formato CIDR; una dirección única es /32. Las llamadas desde cualquier otro lugar se rechazan con 403 «This API key may not be used from the current IP address.» Una clave sin lista propia usa la lista por defecto de la organización (ver Settings más abajo). Las listas de IP permitidas y denegadas de tu organización para el inicio de sesión también se aplican a las claves.

Caducidad

Todas las claves caducan. El valor por defecto es 90 días; la fecha máxima es 365 días a partir de hoy, o menos si tu organización define un máximo inferior. Las claves caducadas dejan de funcionar por sí solas. Un administrador también puede revisar las claves caducadas (POST /api/api-keys/sweep-expired) para marcarlas como inactivas y enviar un evento de webhook api_key.expired por clave.

Rotar, desactivar y revocar

Abre una clave para ver su Identity, Usage (último uso, última IP de uso, total de verificaciones), Module permissions e Rotation history.

• Rotate key crea una clave sucesora con los mismos permisos, ámbitos, lista de redes y entorno. Define el Grace window (days): la clave antigua seguirá funcionando hasta que termine. «0 revokes the old key immediately.» Copia el nuevo secreto de inmediato.
• Deactivate detiene una clave hasta que la vuelvas a Activate. Una clave rotada no se puede reactivar: «A rotated key cannot be reactivated; use its successor.»
• Revoke elimina la clave: «Any integrations using this key will immediately stop working. This action cannot be undone.»
• Edit cambia los permisos de módulo de la clave. Puedes quitar cualquier permiso y añadir solo permisos que tengas tú. Los ámbitos de integración solo se pueden reducir.

En un incidente, un administrador puede revocar en un solo paso todas las claves activas de la organización.

{
    "graceSeconds": 86400
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys/{apiKeyId}/rotate' \
  -H 'Content-Type: application/json' \
  -d '{"graceSeconds":86400}'

{
    "key": {
        "name": "Plant ERP",
        "…": "…"
    },
    "rawKey": "sk_live_…"
}

{
    "message": "Only an active, unexpired key that has not been rotated yet can be rotated.",
    "code": "CONFLICT"
}

Gestionar claves por HTTP

Las claves las gestiona un administrador con sesión iniciada. Una clave de API no puede crear, cambiar ni rotar claves.

{
    "name": "Plant ERP",
    "permissions": [
        "iot_device.devices.read",
        "telemetry.read"
    ],
    "ipAllowlist": [
        "203.0.113.0/24"
    ]
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Plant ERP","permissions":["iot_device.devices.read","telemetry.read"],"ipAllowlist":["203.0.113.0/24"]}'

{
    "key": {
        "name": "Plant ERP",
        "…": "…"
    },
    "rawKey": "sk_live_…"
}

{
    "message": "Select at least one module permission or integration scope."
}

{
    "message": "An API key can only receive permissions you hold yourself."
}

{
    "message": "The expiry date must be in the future."
}

Verificar una clave

{
    "scope": "read"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys/verify' \
  -H 'Content-Type: application/json' \
  -d '{"scope":"read"}'

{
    "valid": true,
    "key": {
        "name": "Plant ERP",
        "…": "…"
    }
}

{
    "valid": false,
    "message": "scope must be a string"
}

{
    "valid": false,
    "message": "Invalid or expired API key."
}

{
    "valid": false,
    "message": "Too many requests."
}

Ajustes

Los administradores establecen la política de claves de la organización en API Keys > ajustes (el botón del engranaje):

Los demás límites que se aplican a las claves están en Errors and rate limits.

Supervisión de claves

• Cada clave registra cuándo y desde qué dirección se usó por última vez.
• Una clave sin uso durante 14 días y que después se usa desde una dirección nueva genera un evento de auditoría («A dormant API key was used from a new address»), como máximo una vez por clave y dirección por hora.
• Cada llamada rechazada con una clave se registra en el registro de auditoría.
• Los webhooks pueden informarle sobre las claves: api_key.created, api_key.updated, api_key.rotated, api_key.deleted, api_key.expired.

Consulte API key hardening para ver una lista de comprobación.