Saltar a contenido

Autenticación y claves de API

Una clave de API es la credencial con la que un sistema — no una persona — lee los datos de un inquilino. Un inquilino puede tener varias, cada una con su propio nombre, ámbitos y caducidad.

¿Autenticas en nombre de un usuario?

Si tu integración necesita actuar como un usuario concreto de HodeiShield —una CLI, un asistente— en vez de como un sistema independiente, usa OAuth en su lugar.

Crear una clave

Desde la consola: Configuración › Integraciones y desarrollo › Integraciones › API Key. Sólo pueden crear y gestionar claves los administradores (de organización o de inquilino); cualquier otro rol recibe 403.

Al crearla defines:

Campo Regla
name 1–80 caracteres
scopes lista de ámbitos (ver abajo); un ámbito desconocido se rechaza
expiresInDays de 1 a 730 días, o sin caducidad (no recomendado)

La respuesta muestra el token en claro una sola vez, con la forma hsk_…. Guárdalo en tu gestor de secretos: si se pierde, la única recuperación es rotar la clave.

Usarla

Authorization: Bearer hsk_...
sequenceDiagram
    participant C as Tu sistema
    participant A as API de HodeiShield

    C->>A: GET /v1/... (Authorization: Bearer hsk_...)
    Note over A: Las comprobaciones van en este orden y la primera que falla responde.
    alt clave ausente, revocada, caducada o desconocida
        A-->>C: 401
    else cuota de la clave, del inquilino o del servicio agotada
        A-->>C: 429 (Retry-After)
    else parámetro de ruta o de consulta inválido
        A-->>C: 400
    else falta el ámbito que exige la operación
        A-->>C: 403 (ámbito necesario en el detalle)
    else todo en orden
        A-->>C: 200 (o 404 si el recurso no existe) + RateLimit-Limit / -Remaining / -Reset
    end

Ámbitos

Un ámbito tiene la forma <módulo>:read o <módulo>:write — por ejemplo supply_risk:read, evidence:read o compliance.nis2:read. Dos reglas importantes:

  • Ningún ámbito implica otro. Leer y escribir requieren dos ámbitos distintos.
  • El cumplimiento es por marco. compliance.nis2:read no da acceso a los datos de ENS.

  • Ámbitos de recurso. changes:read (sólo lectura; no existe changes:write) lee el registro de gestión de cambios en GET /v1/changes. incidents:read lee el registro de incidentes en GET /v1/incidents, y ai_systems:read el registro de sistemas de IA en GET /v1/ai-systems; los dos son de sólo lectura, y ni supply_risk:read ni ai_governance:read los sustituyen.

  • alerts:write reconoce y resuelve alertas (ver más abajo). Ningún ámbito de lectura lo implica, y él no implica ninguno.
  • risks:write mueve una entrada del registro de riesgos por su ciclo de vida (POST /v1/risks/{id}/transition). Igual que alerts:write, es explícito: ningún ámbito de lectura (supply_risk:read incluido) lo implica, él no implica ninguno y las claves existentes no lo ganan. Necesita el módulo supply_risk activo. Sólo un administrador del inquilino puede concederlo, y la clave actúa con el rol del usuario que la creó, leído en cada petición. Una clave de cartera MSSP lo tiene sólo si un administrador de la organización MSSP se lo concedió.
  • act:decide es un ámbito sólo de OAuth, nunca de una clave. Lista y decide las propuestas de acción que podrías aprobar (GET /v1/act/inbox, POST /v1/act/proposals/{id}/approve y .../reject) y sólo se emite a la CLI de HodeiShield, y sólo mientras el servidor lo habilite. Es opcional: la CLI no lo pide por defecto, sólo en un inicio de sesión que haces para decidir, y la pantalla de aprobación lo muestra. Una decisión exige un inicio de sesión confirmado en los últimos 15 minutos (confirmación reforzada: tu segundo factor o la contraseña); pasado ese tiempo, la CLI debe iniciar sesión de nuevo (403 STEP_UP_REQUIRED). Aprobar nunca ejecuta la acción: sólo consiente ejecutarla en la consola en 15 minutos. La bandeja lista sólo las propuestas que puedes aprobar con tu propio rol. Las claves, las claves de cartera, el servidor MCP y otras aplicaciones son rechazados (403 CREDENTIAL_NOT_ALLOWED).
  • email es un ámbito de OAuth, no de módulo: sólo decide si GET /v1/me devuelve user.email a un token de usuario (ver OAuth).

Un ámbito que falta responde 403, con el detalle de qué ámbito era necesario.

El módulo debe estar activo

Tener el ámbito no basta: el módulo que nombra también debe estar activo en el inquilino en el momento de la petición, y un ámbito compliance.<marco> exige además que ese marco esté activado (changes:read exige al menos un marco de cumplimiento activado; incidents:read, el módulo supply_risk, y ai_systems:read, el módulo ai_governance). Vale para las claves de API de inquilino y las claves de cartera igual que para los tokens OAuth. Si no lo está, la respuesta es 403 con error.details.code MODULE_NOT_ENTITLED, error.details.scopes y error.details.modules, más error.details.frameworks cuando el marco está en el plan pero no activado. Una clave nueva no lo arregla: hay que volver a activar el módulo. El uso rechazado queda registrado en el registro de auditoría del inquilino. Ver Errores.

Reconocer y resolver alertas (alerts:write)

alerts:write permite que un sistema —normalmente un SOAR— reconozca y resuelva alertas de la cadena de suministro a través de /v1. Es un ámbito de escritura explícito: ningún ámbito de lectura (supply_risk:read incluido) lo implica, él no implica ninguno de lectura (una clave que sólo tenga alerts:write no puede leer el contenido de las alertas) y las claves existentes no lo reciben. Lo marcas tú al crear la clave; el formulario de creación lo señala como ámbito de escritura. Exige el módulo supply_risk activo, igual que la lectura de alertas.

Quién puede concederlo. El usuario que crea (o rota) la clave debe tener un rol que pueda resolver alertas en la consola. En la llamada no se pide confirmación interactiva, porque quien llama es una automatización; por eso el rol se comprueba al conceder el ámbito. En una clave de cartera MSSP (hsp_…) sólo puede concederlo un administrador de la organización del proveedor, porque la clave actúa entonces en todos los clientes de su conjunto; un analista MSSP no puede. Una clave de cartera que lo lleve debe caducar, como toda clave de cartera.

El rol con el que actúa. Una clave actúa como el usuario que la creó, con el rol de ese usuario leído en cada petición. Al rotar una clave, el usuario que rota pasa a ser el creador de la sucesora. Si ese usuario es degradado, suspendido, eliminado o sale del inquilino (en una clave de cartera: sale del proveedor, o deja de alcanzar ese cliente), la clave pierde el poder al instante y responde 403 (WRITE_ACTOR_UNRESOLVED o ROLE_NOT_PERMITTED). Se aplica la regla de la consola de rol por severidad: la clave de un analista MSSP cierra sólo alertas medias y bajas; las críticas y altas exigen un creador que pudiera cerrarlas en la consola.

Reconocer

curl -X POST "https://api.hodeishield.com/v1/alerts/$ALERT_ID/acknowledge" \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Triaged by playbook PB-114"}'

El cuerpo es opcional; reason (500 caracteres como máximo) se conserva en la auditoría.

Resolver

curl -X POST "https://api.hodeishield.com/v1/alerts/$ALERT_ID/resolve" \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Patched and verified"}'

reason es obligatorio (al menos dos caracteres no vacíos, 500 como máximo) y pasa a ser el resolution_reason de la alerta. Con una clave de cartera, añade -H "X-HS-Tenant: <id del inquilino cliente>" igual que en las lecturas: un inquilino fuera del conjunto de la clave responde 404 (TENANT_NOT_FOUND).

Ambas responden 200 con el estado de la alerta tras la petición, nunca su contenido:

{
  "data": {
    "id": "33333333-3333-4333-8333-333333333333",
    "status": "resolved",
    "acknowledged_at": "2026-11-12T10:15:00Z",
    "resolved_at": "2026-11-12T10:42:00Z",
    "resolution_reason": "Patched and verified",
    "updated_at": "2026-11-12T10:42:00Z"
  },
  "changed": true
}

Errores

Estado error.details.code Cuándo
400 El cuerpo no es un objeto JSON, lleva una clave desconocida, o reason falta, es demasiado corto o supera 500 caracteres
403 INSUFFICIENT_SCOPE La clave no lleva alerts:write
403 ROLE_NOT_PERMITTED El rol del creador no puede gestionar alertas, o es analista MSSP y la alerta es crítica o alta
403 WRITE_ACTOR_UNRESOLVED El creador ya no existe, no está activo o ya no alcanza el inquilino; no se escribió nada
403 LICENCE_INACTIVE La licencia está en periodo de gracia (se rechazan las escrituras; las lecturas no)
404 La alerta no existe en ese inquilino (el id de otro inquilino se ve igual), o TENANT_NOT_FOUND si el inquilino queda fuera del conjunto de una clave de cartera
409 ALERT_RESOLVED Reconocer una alerta que ya está resuelta
409 ALERT_STATE_CHANGED La alerta cambió entre la lectura y la escritura de tu petición; léela otra vez y decide
429 error.details.scope es write_key (presupuesto de escritura de la clave) o service

Repetir una petición

Ambas operaciones son idempotentes. Repetir un cambio ya hecho responde 200 con el estado actual y "changed": false, y no escribe nada: reconocer una alerta ya reconocida, o resolver una ya resuelta (se conserva el primer motivo). changed: true indica que esta petición hizo el cambio. Un 409 ALERT_STATE_CHANGED significa que alguien cambió la alerta en el mismo instante: léela con GET /v1/alerts/{id} y decide; no reintentes a ciegas.

Auditoría y límite de tasa

Cada cambio escribe una entrada en la auditoría del inquilino (ver Registro de auditoría) con el id de la clave (nunca el secreto), el usuario que actúa, la alerta, el estado anterior y el nuevo y el motivo. Una repetición que no cambia nada no escribe ninguna. Las escrituras tienen su propio presupuesto de peticiones por clave, separado de los límites de lectura, así que una ráfaga de lecturas nunca lo gasta ni al revés; ver Límites de tasa.

Rotar una clave

Rotar crea una clave sucesora con el mismo nombre y ámbitos, y mantiene la clave anterior viva durante una ventana de solapamiento configurable (de 0 a 30 días) para que puedas migrar tus sistemas sin una ventana de caída. Al cerrarse la ventana, la clave anterior deja de autenticar.

Revocar una clave

Revocar es inmediato e idempotente: una clave revocada, caducada o desconocida responde siempre el mismo 401, sin distinguir el motivo en la respuesta.

Cuotas por licencia

Las cuotas de la API dependen del nivel de licencia de tu inquilino. Toda respuesta autenticada incluye las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset; al superar la cuota, la respuesta 429 añade Retry-After. Usa esas cabeceras para ajustar tu cliente en tiempo real, en lugar de fijar el límite de antemano.