Skip to content
NuxtBase logo NuxtBase Docs

Platform Setup

The admin area is protected by a named role:

platform_admin

The route guard does not infer this from organization ownership. A user must actually have the platform_admin role in their user record.

What Admin Access Unlocks

Section titled “What Admin Access Unlocks”

A verified user with platform_admin can access:

  • /admin
  • admin stats
  • user moderation
  • organization management
  • plan quota overrides
  • subscription overview
  • waitlist moderation

Without that role, /admin redirects back toward the regular app flow.

Option 1: Bootstrap With INITIAL_ADMIN_EMAIL

Section titled “Option 1: Bootstrap With INITIAL_ADMIN_EMAIL”

The shipped template includes a Nitro plugin that checks:

Terminal window
INITIAL_ADMIN_EMAIL=you@example.com

At startup, it will:

  1. look for an existing user with that email
  2. add platform_admin if the user exists
  3. write an audit log with source env-bootstrap

Important behavior:

  • if the email is missing, nothing happens
  • if the user does not exist yet, the plugin logs a warning and skips the grant
  • if the user already has platform_admin, it does nothing

That means this is a startup-time bootstrap, not a background listener. If the user signs up after the server is already running, restart the app or use the grant script below.

Option 2: Use The Grant Script

Section titled “Option 2: Use The Grant Script”

The template also ships a dedicated bootstrap command:

Terminal window
pnpm admin:grant-platform-admin -- you@example.com

The script:

  • validates the email
  • looks up the target user
  • refuses to create a second platform admin unless you pass --force
  • writes an audit log with source bootstrap-command

If you intentionally need to grant a second platform admin:

Terminal window
pnpm admin:grant-platform-admin -- you@example.com --force
Section titled “Recommended First-Run Flow”
  1. create the first real user account
  2. set INITIAL_ADMIN_EMAIL to that email and restart the app, or run the grant script
  3. sign out and sign back in so the new role appears in session
  4. open /admin
  5. confirm non-admin users are still blocked