# API REST

> Autentícate con tokens de API personales y consulta el inventario y las vulnerabilidades desde scripts.

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`:

```text
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.

[Captura: 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`:

```bash
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:

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

```json
{
  "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:

```bash
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](/es/docs/inventory.md#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](/es/docs/configuration.md#servidor-y-conexiones)). 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.

---

Página HTML: https://infraward.net/es/docs/api/