Administration

Endpoints under /api/admin/* are reserved for operators and elevated users. They cover identity (users, groups, API keys, scope sets), system configuration (config keys, defaults, indexes), and operational visibility (sessions, health).

Most endpoints in this section require either a dedicated *:read/*:write scope or the catch-all admin scope. The admin scope is intentionally broad — it bypasses most fine-grained checks — and should be issued sparingly.

Subsections

Group	What it covers
Users	List, read, create, modify, delete, unlock users; manage avatars and uniqueness checks.
Groups	Group records and group membership.
API Keys	Mint, list, revoke API keys; view the catalogue of scopes a key may carry.
Scope Sets	Named bundles of scopes that get attached to users and API keys.
Configuration	System config keys (read, replace, patch) and mail-config verification.
System Defaults	Force-recreate default objects (themes, blueprints, scope sets, etc.) — used during platform setup or recovery.
Index Management	MongoDB index status, cleanup, and rebuild operations.
Sessions	Admin view of every user's active sessions.
System Health	Service health snapshots for the running deployment.
Bootstrap Activation	One-shot bootstrap endpoint used to mint the first admin during initial deployment.
Admin Push	Receive enrollment tokens from the admin portal.

Scopes Summary

Scope	Reach
admin	Catch-all administrative scope. Required for Configuration, Defaults, Indexes, Sessions, Health, and the bootstrap activation flow.
admin:read	Read-only access to a small slice of administrative metadata (Session filter metadata).
users:read	Reading user records.
users:write	Modifying user records, including avatars, unlock, and uniqueness checks.
groups:read	Reading group records and membership.
groups:write	Creating/modifying groups and managing membership.
apikeys:read	Reading API key records.
apikeys:write	Creating and deleting API keys; viewing the scope catalogue available to keys.
scope_sets:read	Reading scope-set records.
scope_sets:write	Creating, modifying, and deleting scope sets.

Creating a new user is restricted to the admin scope; holders of users:write cannot invite users. This is intentional — see the Create User endpoint for details.

See also

• Authentication — how clients obtain the tokens that carry these scopes.
• Scopes — the complete scope catalogue.
• Conventions — pagination, filtering, and error patterns used across every admin endpoint.