docs/authentication.md

# Authentication

This page describes how to authenticate with the ARF API.

Current status (mixed — not all routers are protected)

- `routes_governance.py`: the entire router requires the `X-Internal-Key` header, verified against `ARF_INTERNAL_API_KEY` (`app/api/deps.py::verify_internal_key`). This fails closed — requests are rejected with 401 if the env var is unset. This is the header arf-gateway injects when proxying to this service.
- `routes_admin.py`: individual `/admin/*` endpoints require an `admin_key` query parameter, verified against `ARF_ADMIN_API_KEY` (`app/api/deps.py`, or the local `verify_admin` dependency in that router). Also fails closed if unset.
- `routes_risk.py`, `routes_intents.py`, `routes_history.py`, `routes_memory.py`: **no auth dependency at all**. If this service is reachable directly (e.g., its public HF Space URL) rather than only through arf-gateway, these routes are open to anyone.

What the code provides

- `app/core/config.py` exposes an `api_key` setting read from `.env`, but no current route checks it — it is not the mechanism in use. The real mechanism is the two env vars above, checked in `app/api/deps.py`.

If you need to lock down the remaining unauthenticated routers

- Add `dependencies=[Depends(verify_internal_key)]` (or a purpose-built dependency) to the `APIRouter(...)` construction in the files listed above, following the pattern already used in `routes_governance.py`.

Notes

- Tests run against a real Postgres connection (`tests/conftest.py`), not SQLite; see the top-level README's Tests section.