Roles
Authorisation is a three-tier monotonic hierarchy:
| Role | Rank | Grants |
|---|---|---|
read_only |
0 | All read and telemetry endpoints |
read_write |
1 | Everything read_only grants, plus event acknowledgement and lifecycle actions |
admin_only |
2 | Everything above, plus key administration, snapshots, audit shipping, and provisioning |
A higher rank satisfies a lower requirement. An unrecognised role held fails
closed; an unrecognised role required also fails closed. There is a fourth,
out-of-hierarchy service role, metrics_scraper, used exclusively by the
Prometheus scrape credential and always paired with a path scope restricting it
to /metrics.
The default is deny. A route with no explicit declaration requires read_only;
opening a route to anonymous access requires an explicit and greppable
decorator, and almost nothing carries one. In particular, GET /api/bng/health
is authenticated — it is a composed operational verdict, not a public liveness
probe. So is /metrics.
Roughly, the surface divides as: the entire read and telemetry surface at
read_only; event acknowledgement and clearing at read_write; and API key
administration, configuration snapshots, audit-shipping destinations, and the
setup wizard at admin_only.