Admin Operations
Mandaitor includes admin-only endpoints for platform operations that are intentionally separate from tenant self-service APIs. These endpoints require a Cognito JWT whose principal belongs to the mandaitor-admins group. They should only be surfaced in internal operator dashboards.
Admin Endpoint Map
The following operations are implemented in the backend and included in the refreshed OpenAPI reference.
| Area | Endpoint | Purpose |
|---|---|---|
| Onboarding queue | GET /admin/onboarding | Lists beta or tenant access requests with optional status filtering and cursor pagination. |
| Onboarding review | POST /admin/onboarding/{requestId}/{action} | Approves or rejects an onboarding request. Supported actions are approve and reject. |
| Tenant detail | GET /admin/tenants/{id} | Returns tenant config, onboarding metadata, API key count, and mandate status counts. |
| Emergency response | POST /admin/tenants/{id}/kill-switch | Revokes all active and suspended mandates for a tenant. |
| System mode | GET /admin/system-mode | Reads the current platform operating mode. |
| System mode | POST /admin/system-mode | Changes the platform operating mode and affects API behavior globally. |
| Cognito proxy | POST /admin/auth/{action} | Proxies selected Cognito authentication actions from the browser. |
| Billing sync | POST /admin/billing/sync-customers | Backfills Stripe customers and optional metered subscriptions for active tenants. |
Tenant Detail Review
GET /admin/tenants/{id} is the operator-facing view for one tenant. It combines tenant configuration, linked onboarding request metadata, the number of API keys, and mandate status counts. The mandate statistics are designed for operational triage, so the implementation caps the sampled mandate set rather than acting as a long-term analytical warehouse.
GET /admin/tenants/tnt_ABC123
Authorization: Bearer <admin-cognito-jwt>
Admin dashboards should use this endpoint before executing irreversible operations such as the kill switch, because it gives the operator context about tenant state and active mandate footprint.
Emergency Kill Switch
POST /admin/tenants/{id}/kill-switch immediately revokes all active and suspended mandates for a tenant. This operation is intended for security incidents, compliance breaches, or contract termination procedures.
The emergency kill switch is irreversible for the affected mandates. Operators should require explicit confirmation in the UI and record the incident context before invoking it.
| Required UI safeguard | Rationale |
|---|---|
| Typed tenant ID confirmation | Reduces accidental execution against the wrong tenant. |
| Incident reason field | Preserves operator context for the audit trail. |
| Final confirmation dialog | Separates review from execution for an irreversible action. |
System Mode
The system mode endpoints allow operators to read and change global operating mode. Current modes include growth, sustain, maintenance, and frozen. Because this affects platform behavior across tenants, dashboard access should be restricted to trusted operators.
const mode = await adminClient.get("/admin/system-mode");
await adminClient.post("/admin/system-mode", {
mode: "maintenance",
reason: "Scheduled database migration",
});
Admin Auth Proxy
POST /admin/auth/{action} proxies selected Cognito operations for the admin browser application. This exists to handle browser-side Cognito identity-provider connectivity constraints while keeping authentication behavior centralized in the backend.
The dashboard should treat this endpoint as an authentication transport and should not expose it as a general tenant API. Only documented admin authentication actions should be sent to the proxy.
Billing Synchronization
POST /admin/billing/sync-customers is a migration and maintenance endpoint that scans active tenants and creates Stripe customer records where missing. When the backend is configured with a metered price ID, it can also create metered subscriptions.
This operation is useful after enabling billing for an existing tenant base. It should be run deliberately by platform administrators and monitored for provider-side failures.