Reference: Admin routes

Status: target state. No admin-only HTTP routes exist. Cross-principal access today is via local-client (loopback) only. This page documents the target route surface for the future admin dashboard.

Today's surface

For the actual present-state HTTP routes, see Reference: Platform APIs. All routes either:

Require no auth (/healthz, /api/apps).
Require a session for the calling principal.
Operate over loopback as local-client.

There is no /_admin/... namespace, no admin: true session claim.

Target admin route prefix

The proposal: every cross-principal admin route lives under /_admin/...:

GET  /_admin/principals
GET  /_admin/principals/:id
POST /_admin/principals/:id/suspend
POST /_admin/principals/:id/unsuspend

GET  /_admin/spaces
GET  /_admin/spaces/:id
POST /_admin/spaces/:id/suspend
POST /_admin/spaces/:id/transfer

GET  /_admin/devices
GET  /_admin/devices/:id
POST /_admin/devices/:id/revoke
POST /_admin/devices/bulk-revoke

GET  /_admin/runtime-hosts
GET  /_admin/runtime-hosts/:id
POST /_admin/runtime-hosts/:id/restart

GET  /_admin/profiles
GET  /_admin/profiles/:id
POST /_admin/profiles/:id/apply

POST /_admin/rollouts
GET  /_admin/rollouts/:id
POST /_admin/rollouts/:id/abort
POST /_admin/rollouts/:id/rollback

GET  /_admin/packages
GET  /_admin/packages/:name
GET  /_admin/packages/:name/versions

GET  /_admin/audit
GET  /_admin/audit/export

GET  /_admin/secrets
POST /_admin/secrets/:id/rotate

Authorization for admin routes

Every /_admin/... route would require either:

A session claim with role: 'platform-admin', OR
A local-client connection.

This is the minimum gate. Stronger: per-route capability check (e.g., audit:read for /_admin/audit).

Authentication

The session model stays the same — mx_session cookie, Bus token for NATS. The target admin extension is a role assertion.

Anti-pattern: admin routes on the user prefix

A common mistake: adding admin behavior to existing user routes (e.g., /api/principals becomes admin-capable when called by an admin). This breaks audit ("who got the data — was it admin or user?") and makes the API harder to authorize at the gateway.

The /_admin/... separation should be maintained. A user with admin role calls /_admin/... for admin work and /api/... for their own data.

Discovery

For the admin UI to know what's available, an OpenAPI-style description at /_admin/spec (target). Today the routes are discoverable only by reading host-platform-http-surface.ts.

CSRF / Origin

Admin routes are POST-heavy; Origin header validation is essential. Target: every POST /_admin/... validates Origin against a known admin UI origin.

Rate limiting

Admin routes should rate-limit per session. A bulk-revoke that fans into thousands of NATS account JWT updates needs to be paced. Today there is no rate-limit; an aggressive admin call could swamp the hub.

Reference: Admin routes ​

Today's surface ​

Target admin route prefix ​

Authorization for admin routes ​

Authentication ​

Anti-pattern: admin routes on the user prefix ​

Discovery ​

CSRF / Origin ​

Rate limiting ​

See also ​