# REST API

> Authenticate with personal API tokens and query the inventory and vulnerabilities from scripts.

Everything the interface does goes through the REST API. Scripts and integrations use it with personal API tokens.

## Base URL

Through the `web` container the API lives under `/api`:

```text
https://infraward.example.com/api
```

## API tokens

Create a token in **Ajustes → Tokens de API** (Settings → API tokens) with **Nuevo token** (New token). Choose:

- **Alcance** (Scope): `read` allows only `GET` and `HEAD` requests. `role` acts with your role's permissions at the time of each request.
- **Caducidad** (Expiry): mandatory, at most 365 days.

[Screenshot: API tokens settings: your tokens and, for administrators, everyone's tokens]

The token is shown once. It starts with `iwt_`, so secret scanners can recognise it. Only its SHA-256 hash is stored. Each user can have up to 25 active tokens. Creating a `role` token requires re-authentication. Administrators see and can revoke every user's tokens.

Send it in the `Authorization` header:

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

A token never has more permissions than its owner. If the owner's role changes, the token follows. Deactivating the account, resetting its password or changing it revokes all its tokens. Some endpoints (changing your password, managing tokens, managing users, revealing vault passwords) require a browser session and reject tokens with `session_required`.

## Examples

Urgent vulnerabilities that are in 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` accepts `low`, `medium`, `high` and `urgent`.

Export the production servers to CSV:

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

The `q` parameter takes the same [search syntax](/docs/inventory.md#search-syntax) as the interface.

## Errors

| Status | Body | Meaning |
|---|---|---|
| 400 | `message` lists the invalid parameters | Validation error. |
| 401 | `Unauthorized` | Missing, expired or revoked token. |
| 403 | `code: api_token_read_only` | A `read` token tried to write. |
| 403 | `code: session_required` | The endpoint only accepts a browser session. |
| 403 | other | Your role lacks the permission. |
| 429 | | Rate limit. Retry later. |

## OpenAPI reference

The API publishes an interactive reference at `/api/docs` and the OpenAPI document at `/api/openapi.json`. In production they are disabled by default. To enable them, set `DOCS_PUBLIC=true` on the `api` service (see [Configuration variables](/docs/configuration.md#server-and-connections)). They are served without authentication when enabled, so consider leaving them off on Internet-facing instances.

## Browser sessions

The web interface uses a session cookie and a CSRF token instead of API tokens. Scripts should not imitate it: use tokens.

---

HTML page: https://infraward.net/docs/api/