Management API

The Management API is the management plane for machine principals (M2M): a dedicated management client uses client-credentials tokens to manage client lifecycles and run read-only user queries, so integrators can automate provisioning.

Status (2026-09-27): the capability is in final implementation (M0); the public documentation registers the contract ahead of the code. How it is enabled and how the endpoints behave follow the release notes of the corresponding version; until end-to-end verification is complete, this page describes a design contract, not verified behavior.

Enabling and seeding

Setting	Default	Description
Auth:Mgmt:Enabled	false	Master switch (deployment-level, read at startup). When disabled the whole route group does not exist (404 externally, absent from discovery)
Auth:Seed:Mgmt:Enabled + Auth:Seed:Mgmt:ClientSecret	false	Seeds the dedicated management client mgmt-api (a confidential client using client credentials) and the mgmt.* scopes; the secret is injected only from a private environment variable

Scopes and authorization

Scope	Allowed operations
mgmt.clients.read	Client list/details
mgmt.clients.write	Client create/update/delete/secret reset
mgmt.users.read	Paginated user queries (zero credential fields)

All three scopes are bound to the resource panda-mgmt-api; endpoints check both audience and scope — a token issued for another resource is rejected even if its scopes are valid. Rules:

• Only confidential clients explicitly granted management scopes can obtain management tokens; interactive application clients are never granted management scopes.
• Tokens are validated online (token-entry validation): revocation takes effect immediately.
• Every write lands in the management audit log (mgmt.client.* action prefix, actor = the calling clientId).

Endpoints

Method and path	Scope	Description
GET /mgmt/v1/users	users.read	Paginated user query (fuzzy search by username/email; the response contains only id, username, email, nickname, status, and creation time)
GET /mgmt/v1/clients	clients.read	Paginated client list
GET /mgmt/v1/clients/{clientId}	clients.read	Client details (secret not included)
POST /mgmt/v1/clients	clients.write	Create; fixed to the authorization code + mandatory PKCE + refresh permission set; a confidential client’s secret is returned exactly once, in this response only
PATCH /mgmt/v1/clients/{clientId}	clients.write	Update display name / callback / post-logout allowlists (only explicitly provided fields are overwritten)
POST /mgmt/v1/clients/{clientId}/reset-secret	clients.write	Reset the secret; the plaintext is returned exactly once
DELETE /mgmt/v1/clients/{clientId}	clients.write	Delete (irreversible)

Error semantics: 401 invalid_token (token invalid or revoked), 403 (missing scope or audience), 429 (rate limit hit; the response carries Retry-After).

Rate limits

Fixed windows along both clientId and IP: 60 for reads, 10 for writes, and the secret endpoints (create/reset) are additionally hard-limited to 6 per minute per IP (starting values, may be tuned per deployment).

Reserved clients

First-party and platform-level clients (me-web, admin-web, mgmt-api, fleet-api) are read-only as far as the Management API is concerned: update, delete, and secret reset are always rejected — the lifecycle of these clients belongs to deployment orchestration and seed reconciliation.

Boundaries

• User writes (account creation, freezing, role changes) are not on the Management API: they still go through the manual channel in the admin console.
• Read scopes for sign-in logs / audit are not part of the frozen M0 surface.
• The Management API does not appear in discovery metadata; the /mgmt/v1 path prefix is explicitly separated from the OIDC protocol endpoints (/connect/*).