# Admin endpoints

`smallwebwaf` answers these requests itself, on the app's own address and
through traefik like any other request. Apart from the health check, each needs
a token, sent as `Authorization: Bearer <token>`, and goes through every check
any other request goes through. It is answered where another request would be
passed to the app: a banned client stays refused, and each request counts toward
rate limiting. A missing or wrong token is answered `401`, in `observe` mode
too. Such a refusal counts toward the error burst, so a client guessing tokens
is soon banned. While a token is unset, its endpoints answer `404`.

- `GET /_smallwebwaf/healthz`: `200` and `ok`, to anyone, before any check and
  without asking the app.
- `GET /_smallwebwaf/metrics`: the metrics, for `SWWAF_METRICS_TOKEN` (see
  [`metrics.md`](metrics.md)).
- `GET /_smallwebwaf/bans`: every ban held, under `bans`, each as `bans.json`
  lists it. Needs `SWWAF_ADMIN_TOKEN`, as do the three below.
- `POST /_smallwebwaf/bans`: bans a netblock. The body is a JSON object of
  `netblock`, `duration` and, if you like, `reason`. `netblock` is a netblock
  such as `203.0.113.0/24`, or a client's address. A client's address bans its
  IPv4 netblock (`SWWAF_BAN_SCOPE_V4_PREFIX`) or its IPv6 group. `duration` is a
  duration such as `1h` or `7d`, or `permanent`. The ban starts at once, with
  the cause `admin`. A bad body is answered `400`, saying what is wrong:
    - one that is not such an object, or has another field;
    - one longer than 4 KiB;
    - one that names an IPv4-mapped netblock, or an address with a zone.
- `DELETE /_smallwebwaf/bans/<client>`: lifts every active ban covering the
  address `<client>`. It answers `404` when none is active.
- `GET /_smallwebwaf/clients/<ip>`: what `smallwebwaf` knows of the client.
  Under `client`, its counters and history as `clients.json` holds them, or
  `null` when it has never been seen. Under `bans`, every ban covering the
  address, with its notes.

An admin whose own address is banned lifts that ban by editing `bans.json` (see
[`bans.md`](bans.md)).