Authentication

LaunchSaaS uses Better Auth for authentication, providing a flexible and secure system with multiple authentication methods, session management, and role-based access control.

The boundary is:

• apps/launchsaas/src/lib/auth/auth.ts owns Better Auth server construction
• apps/launchsaas/src/lib/auth/auth-client.ts owns Better Auth client construction
• apps/launchsaas/src/components/layout/better-auth-ui-provider.tsx bridges the auth client with router, i18n, and client-safe auth UI settings
• packages/design-system/ui/src/components/{auth,user,settings} contains the source-vendored Better Auth UI components consumed by the app

Setup

1. Generate Better Auth Secret

The BETTER_AUTH_SECRET is a random string used for encryption and generating hashes. Generate one using VictoryHub or run:

openssl rand -base64 32

Add it to your .env file:

BETTER_AUTH_SECRET="your-generated-secret-key"

2. Configure Email/Password (Optional)

Email/password authentication is enabled by default via the emailPasswordEnabled flag in auth.ts. When enabled and an email provider is configured, users can sign up, sign in, verify their email, and reset their password.

To disable it, set the flag to false:

// apps/your-app/src/lib/auth/auth.ts
const emailPasswordEnabled = false; // default is true

3. Configure Magic Link (Optional)

Magic link is disabled by default. To enable it:

1. Make sure an email provider is configured (required for sending the link)
2. Open apps/your-app/src/lib/auth/auth.ts and set magicLinkEnabled to true:

const magicLinkEnabled = true; // was false

Once enabled, Better Auth will send a one-time sign-in link to the user's email. The sign-in UI automatically shows the magic link option.

4. Configure GitHub OAuth (Optional)

1. Go to GitHub Developer Settings
2. Click on "OAuth Apps" → "New OAuth App"
3. Fill in the registration form:
   • Application name: Your app name
   • Homepage URL: http://localhost:3000 (or your production URL)
   • Authorization callback URL: http://localhost:3000/api/auth/callback/github
4. Click "Register application"
5. Generate a client secret
6. Add to your .env file:

NEXT_PUBLIC_GITHUB_CLIENT_ID="your-client-id"
GITHUB_CLIENT_SECRET="your-client-secret"

5. Configure Google OAuth (Optional)

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Go to Credentials → Create Credentials → OAuth client ID
4. Configure OAuth consent screen if prompted
5. Create OAuth Client ID:
   • Application type: Web application
   • Authorized JavaScript origins: http://localhost:3000
   • Authorized redirect URIs: http://localhost:3000/api/auth/callback/google
6. Add to your .env file:

NEXT_PUBLIC_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-client-secret"

5. Configure CAPTCHA (Optional)

CAPTCHA activates automatically when CAPTCHA_SECRET_KEY is set. No code change needed.

See the Captcha guide for provider options and setup instructions.

Features

LaunchSaaS authentication includes:

• Email/Password - Sign up, sign in, email verification, and password reset (enabled by default; set emailPasswordEnabled = false in auth.ts to disable)
• Magic Links - Passwordless authentication (disabled by default; set magicLinkEnabled = true in auth.ts to enable)
• Social Login - Google and GitHub OAuth (enabled by adding client ID env vars)
• CAPTCHA - Bot protection via Cloudflare Turnstile, Google reCAPTCHA, hCaptcha, or CaptchaFox (enabled by adding CAPTCHA_SECRET_KEY; see Captcha guide)
• Session Management - Server-side session handling
• Role-Based Access - User and admin roles
• App-Owned Auth Wiring - Server, client, and auth UI stay in your app

User Roles

User Role

Default role for all registered users. Has access to:

• Billing page (/billing)
• Settings (/settings/profile, /settings/security, /settings/preferences)
• Subscription management

Admin Role

Elevated privileges for administrators. Has access to:

• Admin panel (/admin/users, /admin/orders, /admin/entitlements)
• User management
• All user features

Production Checklist

Before going to production, ensure:

• BETTER_AUTH_SECRET is a strong, unique secret
• NEXT_PUBLIC_APP_URL is set to your production domain
• Social OAuth apps are configured with production callback URLs
• Email service is configured and domain verified

References

• Better Auth Documentation
• Better Auth Plugins

Next Steps