2GT-RichandClaude Opus 5
7b994ad935
Closes #130. Multi-site, not multi-tenancy: a site is a named collection of devices whose clients, events, topology and dashboards are viewed separately. Sites separate what you see, not who you are — the admin/manage/read-only roles are unchanged and every user sees every site. Per-site permissions would have multiplied the work for a need nobody stated. Two measurements decided the design. Every device-derived table hangs off devices(id) — 25 of 50 tables, 35 foreign keys — so a single site_id column on devices scopes clients, events, topology, backups and the rest transitively. No other table needed one. The frontend has 162 useQuery call sites across 57 files. Threading a site through each would be a large change that leaves a permanent trap: every future query another chance to forget. The site is injected in the existing axios interceptor instead, beside the auth token, so a new query is scoped by default. Only 23 collection routes needed filtering; the 131 per-device routes are already scoped by their device. Existing installs are untouched. Migration creates one "Default Site", adopts every device into it, and a single-site install never meets the concept. An absent X-Site-Id header means unscoped, so existing API tokens and scripts behave exactly as before. Polling stays fleet-wide. Sites are a view over data already gathered, not a change to how it is gathered — a device does not stop being monitored because you are looking elsewhere. Rogue-AP detection scopes the scans but keeps the "these are ours" BSSID set fleet-wide, or your own AP in another site reads as an evil twin. Bulk actions do obey the selector: an operation that silently spanned two customers is the blast radius the wave guards exist to contain. Four rounds of defects came out of testing the UI rather than the API, and the first is the one worth recording. Switching sites called queryClient.clear(), which empties the cache and reviews as correct. It isn't: clear() destroys each query but a *mounted* observer keeps its own reference and last result, so every rendered page went on showing the previous site's data. The QueryClient is now keyed on the site, which remounts the tree against an empty cache. Three tests pin the old behaviour down so the shortcut cannot return. The others: an unscoped fallback path behind the Connected Clients chart; Config Health, TX retries and the activity feed reading fleet-wide; and site_id added to the device list query but none of the other four that build a device payload, so the Site field could not read its own value and appeared to reject every change while the writes were landing. That last one is now structural — DEVICE_BASE_COLUMNS is shared by all five, with a test that fails when a device payload is hand-rolled, and which found two further instances while being written. Frontend tests were never run by CI despite vitest being configured and six suites existing; they now run in both the workflow and ci-preflight. Verified against a live four-device fleet: the migration left every figure identical, an empty site returns zero from every read endpoint, moving a device carries its history with it, and deleting a site with devices is refused. Minor bump rather than patch: sites change the shape of the product rather than adding to it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
# API and automation
|
|
|
|
[← Documentation index](README.md)
|
|
|
|
The web UI is a client of the same REST API you can drive yourself. Anything the interface
|
|
does is available to a script.
|
|
|
|
## Scoped API tokens
|
|
|
|
Issue tokens under **Settings → Automation**.
|
|
|
|
- Prefix `mtm_…`, with **read** or **write** scope and an optional expiry
|
|
- Shown **once** on creation — only a SHA-256 hash is stored
|
|
- Mapped onto the role model: no token can perform admin actions or manage other tokens,
|
|
regardless of scope
|
|
|
|
```bash
|
|
curl -sk https://manager.example.com/api/devices \
|
|
-H "Authorization: Bearer mtm_your_token_here"
|
|
```
|
|
|
|
A token with `read` scope is rejected on any mutating request, so a monitoring integration
|
|
cannot change your network even if the token leaks.
|
|
|
|
## Session authentication
|
|
|
|
The UI authenticates with a JWT obtained from `/api/auth/login`, optionally followed by
|
|
`/api/auth/totp/verify` when two-factor is enabled. Tokens are bearer credentials and are
|
|
sent in the same `Authorization` header.
|
|
|
|
For scripting, prefer an API token — it is scoped, revocable, and unaffected by password
|
|
or 2FA changes.
|
|
|
|
## Endpoints worth knowing
|
|
|
|
| Endpoint | Purpose |
|
|
|---|---|
|
|
| `GET /api/devices` | Fleet inventory with status, model, versions and serials |
|
|
| `POST /api/devices/:id/sync` | Force an immediate full collection for one device |
|
|
| `GET /api/devices/:id/management-path` | How the manager reaches a device, with the reason for each hop |
|
|
| `POST /api/devices/:id/preflight` | Analyse a change **without applying it** |
|
|
| `POST /api/devices/:id/change-guard/probe` | Report which safety mechanisms the device supports |
|
|
| `GET /api/devices/:id/config-health` | Latest standing-audit findings |
|
|
| `GET /api/topology` | Graph of devices, links, external nodes, and distrusted identifiers |
|
|
| `GET /api/operations/insights` | The dashboard's "things to handle" feed |
|
|
| `GET /api/sites` | Sites with device counts (see [Sites](sites.md)) |
|
|
|
|
### Scoping a request to one site
|
|
|
|
Collection endpoints accept an `X-Site-Id` header (or `?site_id=`) that limits the
|
|
response to devices in that site:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer $TOKEN" -H "X-Site-Id: 2" \
|
|
https://mtm.example.com/api/devices
|
|
```
|
|
|
|
**Omitting it means unscoped**, returning the whole fleet exactly as before sites
|
|
existed — existing scripts and tokens need no change. Per-device endpoints
|
|
(`/api/devices/:id/...`) are already scoped by the device itself and ignore the header.
|
|
|
|
One thing to know if you create devices via the API: a device joins the site the
|
|
request was scoped to, falling back to the default site. A device belonging to no site
|
|
is invisible whenever a site is selected, so this is set rather than left null.
|
|
|
|
`preflight` is the useful one for automation: it returns the same verdict the UI shows,
|
|
so a pipeline can refuse its own change before touching the device. See
|
|
[Change Guard](change-guard.md#lockout-prediction).
|
|
|
|
## Applying a guarded change from a script
|
|
|
|
Guarded endpoints return **409** with `lockout: true` and a verdict when a change is
|
|
predicted to sever management. To proceed anyway, resend with `confirm_lockout: true` —
|
|
the change then runs under Change Guard, so a mistake still recovers itself.
|
|
|
|
```bash
|
|
# Refused, with an explanation
|
|
curl -sk -X PUT https://manager.example.com/api/devices/8/ports/ether1/vlan \
|
|
-H "Authorization: Bearer mtm_…" -H 'Content-Type: application/json' \
|
|
-d '{"pvid":99,"tagged_vlans":[],"untagged_vlans":[99]}'
|
|
|
|
# Accepted, relying on auto-revert
|
|
curl -sk -X PUT https://manager.example.com/api/devices/8/ports/ether1/vlan \
|
|
-H "Authorization: Bearer mtm_…" -H 'Content-Type: application/json' \
|
|
-d '{"pvid":99,"tagged_vlans":[],"untagged_vlans":[99],"confirm_lockout":true}'
|
|
```
|
|
|
|
A successful guarded change returns a `guard` block describing what happened —
|
|
`confirmed`, `auto_reverting`, or an `unprotected_reason` when the safety net could not be
|
|
armed. Check it rather than relying on the HTTP status alone.
|
|
|
|
## Webhooks
|
|
|
|
For push rather than poll, see [Alerting → outbound webhooks](alerting.md#outbound-webhooks).
|
|
Deliveries are HMAC-SHA256 signed and respect alert rules, cooldowns and maintenance
|
|
windows.
|