Platform admin overview

The platform-admin console lives at /admin in the client app and gives anyone with User.platformAdmin === true cross-tenant tooling for users, organizations, billing, audit logs, and feature flags. It's distinct from the per-org settings that tenant owners use — the routes, the gate, and the audit prefixes are all separate.

When to use the platform admin

• You're operating the boilerplate as a SaaS host and need to suspend a tenant, change someone's plan, or revoke an attacker's session without writing SQL.
• You're investigating an incident and need to search audit events across all tenants for a specific actor or action.
• You're rolling out a feature gradually and need to flip a flag or change a rollout percentage at runtime.

When NOT to use the platform admin

• For a tenant's own org settings — tenant owners use /settings/* for their own organization. The platform admin shouldn't be where day-to-day tenant work happens.
• As a substitute for proper RBAC inside a tenant — within an org, role-based permissions still apply (User.platformAdmin is orthogonal to OrganizationMember.role).

Sections

• Bootstrap — first-run owner setup wizard and recovery CLI.
• Managing admins — promote / demote, last-admin invariant.
• Managing users — suspend, reactivate, force logout, force password reset, soft-delete, resend verification, impersonate.
• Managing organizations — suspend / reactivate / soft-delete / transfer ownership.
• Billing admin — change plan, extend trial, cancel, list invoices.
• Audit — cross-tenant filterable event log.
• Feature flags — toggle and rollout-percentage controls.

Architecture

Each capability lives in its owning bounded context — IAM admin actions in modules/iam/, tenancy admin in modules/tenancy/, etc. Cross-cutting pieces (impersonation, bootstrap, the requirePlatformAdmin middleware, the platform overview) sit in modules/platform/. URLs all live under /api/v1/platform/* and the corresponding pages under /admin/* for a single discoverable surface.

Every mutation emits an audit event with the actor's real userId, not the impersonated one. See Audit for the action prefix conventions (platform.user.*, platform.org.*, platform.feature_flag.*).