Admin REST API
A token-authenticated REST API on the admin listener (admin.addr, default
:8081). POST /api/login returns a bearer token for the rest. The API serves
two distinct resources: /api/clients are MQTT credentials/ACL, while
/api/users are console operator accounts.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/login | Authenticate; returns a bearer token |
| GET | /api/overview | Broker metrics (connections, counters, uptime) |
| GET | /api/sessions | Active and stored sessions |
| DELETE | /api/sessions/{id} | Disconnect a session (?forget=1 erases persistent state) |
| GET | /api/topics | Recent-traffic topic view |
| DELETE | /api/topics | Clear the recent-traffic view |
| GET | /api/clients | Builtin MQTT credentials |
| PUT/DELETE | /api/clients/{name} | Create-or-update / delete an MQTT credential |
| GET | /api/clients/blocked | Blocked clients |
| POST | /api/clients/blocked | Block a client |
| DELETE | /api/clients/blocked?kind=…&value=… | Unblock |
| GET | /api/clients/unauthorized | Refused CONNECT attempts |
| GET | /api/users | Console operator accounts |
| PUT/DELETE | /api/users/{name} | Manage a console operator |
| GET | /api/auth/providers | Provider rows (basic, x509, jwt, http) with configured flags |
| PUT | /api/auth/anonymous | Toggle anonymous access |
| GET | /api/stream?token=… | Server-sent events (token in the query — EventSource can't set headers) |
$SYS topics
The broker publishes metrics under $SYS/# every admin.sys_interval_s seconds
as non-retained QoS 0 messages — subscribe to $SYS/# explicitly (a root
# won't match) and expect the first values on the next interval.