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¶
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:readno da acceso a los datos de ENS. -
Ámbitos de recurso.
changes:read(sólo lectura; no existechanges:write) lee el registro de gestión de cambios enGET /v1/changes.incidents:readlee el registro de incidentes enGET /v1/incidents, yai_systems:readel registro de sistemas de IA enGET /v1/ai-systems; los dos son de sólo lectura, y nisupply_risk:readniai_governance:readlos sustituyen. alerts:writereconoce y resuelve alertas (ver más abajo). Ningún ámbito de lectura lo implica, y él no implica ninguno.risks:writemueve una entrada del registro de riesgos por su ciclo de vida (POST /v1/risks/{id}/transition). Igual quealerts:write, es explícito: ningún ámbito de lectura (supply_risk:readincluido) lo implica, él no implica ninguno y las claves existentes no lo ganan. Necesita el módulosupply_riskactivo. 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:decidees 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}/approvey.../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 (403STEP_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 (403CREDENTIAL_NOT_ALLOWED).emailes un ámbito de OAuth, no de módulo: sólo decide siGET /v1/medevuelveuser.emaila 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.