Skip to content
NuxtBase logo NuxtBase Docs

Authentication

NuxtBase ships with a full authentication layer, not just a login form.

From the current template code, the auth stack includes:

  • email and password
  • Google and GitHub OAuth
  • email verification
  • password reset
  • magic links
  • email OTP
  • two-factor authentication
  • passkeys
  • organization-aware sessions
  • platform admin-aware redirects
  • configurable auth method toggles

That makes auth one of the core product systems in the template. It affects dashboard access, admin access, invitations, billing, and any route protected by a verified session.

Auth Method Toggles

Section titled “Auth Method Toggles”

Every login method can be enabled or disabled via the NUXT_DISABLED_AUTH_METHODS environment variable. By default, all methods are enabled. To disable specific methods, set a comma-separated list:

Terminal window
NUXT_DISABLED_AUTH_METHODS=passkey,magicLink

Available method names: password, emailOtp, magicLink, passkey, google, github.

The template enforces two startup constraints:

  1. at least one sign-in method must remain enabled
  2. at least one onboarding-capable method (password, google, or github) must remain enabled

If neither constraint is met, the app fails at startup with a descriptive error instead of starting in a broken state.

The toggle affects:

  • server-side: Better Auth plugin registration, API endpoint access, and a server hook that blocks disabled method calls even if hit directly
  • frontend: conditional rendering of buttons, forms, and settings sections via the useAuthMethods composable
  • page access: route middleware redirects users away from pages that depend on a disabled method (e.g. /forgot-password when password is off)

Reading Order

Section titled “Reading Order”
Email & Password Register, verify, log in, reset passwords, and use magic links.
OAuth Understand how Google and GitHub sign-in behave in the shipped UI.
Two-Factor Authentication See how TOTP setup, backup codes, and login challenges work.
Passkeys Use passkey sign-in on the login page and manage passkeys in settings.
Email Verification Follow the verification email, confirmation page, and callback flow.

What To Validate First

Section titled “What To Validate First”

After your local app is running, verify these flows before changing auth logic:

  1. create a new account
  2. confirm the verification email arrives
  3. verify the account and reach the dashboard
  4. sign out and sign back in
  5. confirm protected routes redirect anonymous users to login
  6. confirm unverified users are redirected back to the verify-email confirmation page
  7. if relevant, test OAuth, 2FA, and passkey flows

Auth Architecture Summary

Section titled “Auth Architecture Summary”

There are three practical layers to keep in mind:

  1. Better Auth server configuration in server/utils/auth.ts
  2. client-side auth calls through app/utils/auth-client.ts
  3. route protection through app/middleware/auth.global.ts and app/utils/auth-route.ts

The route guard behavior is especially important:

  • anonymous users are redirected from protected routes to /login
  • unverified users are redirected to /auth/confirm?mode=verify-email
  • verified users who open /login or /register are redirected into the app
  • verified platform admins are redirected to /admin instead of /dashboard

Product Boundary

Section titled “Product Boundary”

Treat authentication as product infrastructure, not as a one-off setup task. If you change providers or session rules, review how those changes affect billing, organizations, and admin access at the same time.