Skip to content
B2B SaaS StarterSign in
Knowledge sections

System admin

Global user management via Better Auth's admin plugin, distinct from any Workspace Role.

adminsystem-admin
On this page

A System Admin is a user with global user-management permissions through Better Auth's admin plugin. System Admin is not a Workspace Role; it operates at the user level. packages/auth/src/index.ts registers admin({ adminRoles: ['admin'] }), so users whose user.role = 'admin' are System Admins.

What's wired today

The /admin route renders a global users table (name, email, system role, status) with per-row actions, a cross-workspace role editor, and a global audit-event table sourced from AuditEventLog.listGlobal. The actions go through the PlatformUserAdmin capability, never straight to the plugin:

  • Ban / Unban: blocks or restores sign-in. Audited as system_admin.user_banned / system_admin.user_unbanned.
  • Change workspace role: sets a user's Workspace Role in one workspace. Audited as system_admin.user_role_changed.
  • Impersonate: opens an Impersonation Session as that user (below). Audited as system_admin.impersonation_started / system_admin.impersonation_stopped.

Password reset and account creation from /admin are not surfaced.

Impersonation

A System Admin can browse the app as another user to reproduce what they see. The session is Better Auth's admin-plugin impersonation (ADR 0054):

  • One hour, then it ends on its own. Stop earlier from the banner.
  • Visible the whole time. Every page in the app shell shows a banner naming the impersonated user with a Stop impersonating button. Stop restores the admin's own session and returns to /admin.
  • No elevation. The session has exactly the impersonated user's roles: it cannot open /admin, and a workspace the user is not a member of stays a 404. System Admins cannot be impersonated.
  • Locked actions. The session cannot change the user's password, two-factor settings, or email, or delete the account. The auth endpoints answer 403 and the controls are hidden on /account. The real account holder makes those changes.
  • Recorded on both sides. system_admin.impersonation_started and system_admin.impersonation_stopped name the admin as actor and the user as target, so both /admin's trail and the user's workspace audit page show it. The impersonated user also receives a Notification in each of their workspaces saying who started the session.

What a System Admin cannot do

  • Sign in to an arbitrary workspace's UI without being a Member, or without an Impersonation Session as one
  • Bypass workspace billing or governance limits
  • Impersonate another System Admin, or change an impersonated user's credentials

Audit trail

Every System Admin action emits an Audit Event with actor, target user, and action type, through the same AuditEventLog capability the rest of the app writes to. The Better Auth admin endpoints called directly from a client are audited by the auth catchall as system_admin.* success/failure pairs; the /admin UI's own actions are audited by the capability. See ARCHITECTURE.md §Audit log.

When to grant System Admin

System Admin is for the operators of the deployment, not for workspace owners. Grant it sparingly. A workspace owner does not need System Admin to manage their workspace.