API REST

Ver en Markdown

Todo lo que hace la interfaz pasa por la API REST. Los scripts y las integraciones la usan con tokens de API personales.

URL base

A través del contenedor web, la API está bajo /api:

https://infraward.example.com/api

Tokens de API

Crea un token en Ajustes → Tokens de API con Nuevo token. Elige:

Alcance: read solo permite peticiones GET y HEAD; role actúa con los permisos de tu rol en el momento de cada petición.
Caducidad: obligatoria, como mucho 365 días.

Ajustes de tokens de API: tus tokens y, para los administradores, los de todos los usuarios

El token se muestra una sola vez. Empieza por iwt_, para que los escáneres de secretos lo reconozcan, y solo se guarda su hash SHA-256. Cada usuario puede tener hasta 25 tokens activos. Crear un token role pide reautenticación. Los administradores ven y pueden revocar los tokens de todos los usuarios.

Envíalo en la cabecera Authorization:

export INFRAWARD_TOKEN=iwt_...
curl -s -H "Authorization: Bearer $INFRAWARD_TOKEN" \
  "https://infraward.example.com/api/assets/tree?q=tag:prod"

Un token nunca tiene más permisos que su dueño. Si cambia el rol del dueño, el token cambia con él. Desactivar la cuenta, restablecer su contraseña o cambiarla revoca todos sus tokens. Algunos endpoints (cambiar la contraseña, gestionar tokens, gestionar usuarios, revelar contraseñas de la caja fuerte) exigen una sesión del navegador y rechazan los tokens con session_required.

Ejemplos

Vulnerabilidades urgentes que están en CISA KEV:

curl -s -H "Authorization: Bearer $INFRAWARD_TOKEN" \
  "https://infraward.example.com/api/vulnerabilities?minPriority=urgent&kev=true"

{
  "items": [
    {
      "vulnerabilityId": "CVE-2026-111497",
      "severity": "HIGH",
      "fixable": true,
      "priority": { "score": 100, "band": "urgent", "reasons": [{ "code": "kev" }, { "code": "epss", "epss": 0.55483 }, { "code": "port", "ports": [80] }] }
    }
  ],
  "total": 1,
  "hidden": {}
}

minPriority admite low, medium, high y urgent.

Exportar los servidores de producción a CSV:

curl -s -H "Authorization: Bearer $INFRAWARD_TOKEN" \
  "https://infraward.example.com/api/assets/export?format=csv&q=tag:prod" -o prod.csv

El parámetro q usa la misma sintaxis de búsqueda que la interfaz.

Errores

Estado	Cuerpo	Significado
400	`message` enumera los parámetros no válidos	Error de validación.
401	`Unauthorized`	Token ausente, caducado o revocado.
403	`code: api_token_read_only`	Un token `read` ha intentado escribir.
403	`code: session_required`	El endpoint solo acepta una sesión del navegador.
403	otro	Tu rol no tiene el permiso.
429		Límite de peticiones. Vuelve a intentarlo más tarde.

Referencia OpenAPI

La API publica una referencia interactiva en /api/docs y el documento OpenAPI en /api/openapi.json. En producción están desactivados por defecto. Para activarlos, define DOCS_PUBLIC=true en el servicio api (consulta Variables de configuración). Cuando están activos se sirven sin autenticación, así que es mejor dejarlos apagados en instancias expuestas a Internet.

Sesiones del navegador

La interfaz web usa una cookie de sesión y un token CSRF en lugar de tokens de API. Los scripts no deberían imitarla: usa tokens.