Authentication Methods | ShipSaaS Documentation

The boilerplate includes a comprehensive Better Auth system with multiple authentication methods that can be enabled/disabled via environment variables.

Available Authentication Methods

Core Authentication Methods

✅ Credentials (Email/Password)

Always available - classic email/password login

emailAndPassword: enabled

🔗 Magic Link

Passwordless authentication via email

magicLink plugin

🔐 Two-Factor Authentication

TOTP (apps) + OTP (SMS/email) support

twoFactor plugin

🌐 Social Authentication

Google, GitHub, Facebook, Apple login

socialProviders (OAuth)

Advanced Authentication Features

🔑 API Keys

Generate API keys for programmatic access

apiKey plugin

🎫 Bearer Tokens

JWT tokens for API authentication

bearer plugin

🏢 Organizations

Multi-tenant workspaces with roles

organization plugin

👑 Admin Functions

Administrative user management

admin plugin

Environment Variables Configuration

Core Requirements: At minimum, you need BETTER_AUTH_SECRET and BETTER_AUTH_URL to get authentication working.

Core Authentication Controls

bash

# Better Auth Core
BETTER_AUTH_SECRET="your-secret-key"
BETTER_AUTH_URL="http://localhost:3000"
BETTER_AUTH_TRUSTED_ORIGINS="http://localhost:3000"

# Email Features (required for magic link, verification, password reset)
RESEND_API_KEY="re_your_api_key"
EMAIL_FROM="noreply@yourdomain.com"

Feature Toggle Variables

bash

# Control which auth methods are available
NEXT_PUBLIC_AUTH_METHODS="credential,magiclink,google,github"
# Options: credential, magiclink, google, github, facebook, apple

bash

# Email verification
NEXT_PUBLIC_BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=true

# Password management
NEXT_PUBLIC_BETTER_AUTH_CHANGE_PASSWORD=true
NEXT_PUBLIC_BETTER_AUTH_CHANGE_EMAIL=true

# Two-Factor Authentication
NEXT_PUBLIC_BETTER_AUTH_2FA_ENABLE=true
NEXT_PUBLIC_BETTER_AUTH_2FA_SKIP_VERIFICATION_ON_ENABLE=true

# API Key management
NEXT_PUBLIC_BETTER_AUTH_TOKEN_MANAGEMENT=true

bash

# Google OAuth
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# GitHub OAuth
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Facebook OAuth
FACEBOOK_CLIENT_ID="your-facebook-app-id"
FACEBOOK_CLIENT_SECRET="your-facebook-app-secret"

# Apple OAuth
APPLE_CLIENT_ID="your-apple-service-id"
APPLE_CLIENT_SECRET="your-apple-private-key"

Organization & Billing

Billing Mode: Choose between individual user billing or organization-based billing.

bash

# Multi-tenant mode
NEXT_PUBLIC_BILLING_MODE="organization" # or "user"

# Available pages/features
NEXT_PUBLIC_ENABLED_PAGES="organization,invitation,account,settings,subscription,notifications,admin"

Quick Configuration Examples

Minimal Setup (Email/Password only)

bash

BETTER_AUTH_SECRET="your-secret"
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_AUTH_METHODS="credential"
NEXT_PUBLIC_BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=false

Full Features Setup

bash

# Core
BETTER_AUTH_SECRET="your-secret"
BETTER_AUTH_URL="http://localhost:3000"

# Email service
RESEND_API_KEY="re_your_key"
EMAIL_FROM="noreply@yourdomain.com"

# All auth methods
NEXT_PUBLIC_AUTH_METHODS="credential,magiclink,google,github"

# All user features
NEXT_PUBLIC_BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=true
NEXT_PUBLIC_BETTER_AUTH_2FA_ENABLE=true
NEXT_PUBLIC_BETTER_AUTH_TOKEN_MANAGEMENT=true

# Social providers
GOOGLE_CLIENT_ID="your-google-id"
GOOGLE_CLIENT_SECRET="your-google-secret"
GITHUB_CLIENT_ID="your-github-id"
GITHUB_CLIENT_SECRET="your-github-secret"

File Structure & User Pages

All authentication features are organized in dedicated route groups and component folders for easy navigation and maintenance.

📁 Authentication Routes

Location: src/app/[locale]/(auth)/

All public authentication pages grouped under a dedicated layout.

src/app/[locale]/(auth)/
├── login/                        # Login page with all methods
├── register/                     # User registration
├── logout/                       # Logout confirmation
├── reset-password/               # Password reset form
└── verify-request/               # Email & 2FA verification
    ├── totp/                     # TOTP verification
    ├── otp/                      # OTP verification
    └── recovery/                 # Recovery codes verification

🧩 Authentication Components

Location: src/components/features/auth/

Reusable authentication form components used across all auth pages.

src/components/features/auth/
└── forms/                        # All authentication forms
    ├── login.tsx                 # Main login form
    ├── credential-form.tsx       # Email/password form
    ├── magic-link-form.tsx       # Magic link form
    ├── register-form.tsx         # Registration forms
    └── recovery-code-form.tsx    # 2FA recovery form

👤 User Account Management

Location: src/app/[locale]/(app)/account/

Protected pages requiring user authentication. Access controlled by auth middleware.

src/app/[locale]/(app)/account/
├── settings/                     # Profile & security settings
├── api-keys/                     # API key management
├── subscription/                 # Subscription management
├── notifications/                # Notification preferences
├── organizations/                # Organization management
│   └── [id]/                     # Organization details & settings
└── invitations/                  # Organization invitations
    └── [id]/                     # Accept/decline invitations

Method-Specific Documentation

Ready to dive deeper? Each authentication method has its own detailed guide with configuration examples and troubleshooting tips.

📧

Credentials Authentication

Email/password setup and configuration

🔗

Magic Link

Passwordless authentication via email

🔐

Two-Factor Authentication

TOTP and OTP setup and usage

🌐

Social Authentication

Google, GitHub, Facebook, Apple configuration

🔑

API Keys & Tokens

Programmatic access management

🏢

Organizations

Multi-tenant workspace management

Security First: All authentication methods include built-in rate limiting, CSRF protection, secure session management, and XSS prevention.

The boilerplate includes a comprehensive Better Auth system with multiple authentication methods that can be enabled/disabled via environment variables.

Available Authentication Methods

Core Authentication Methods

✅ Credentials (Email/Password)

Always available - classic email/password login

emailAndPassword: enabled

🔗 Magic Link

Passwordless authentication via email

magicLink plugin

🔐 Two-Factor Authentication

TOTP (apps) + OTP (SMS/email) support

twoFactor plugin

🌐 Social Authentication

Google, GitHub, Facebook, Apple login

socialProviders (OAuth)

Advanced Authentication Features

🔑 API Keys

Generate API keys for programmatic access

apiKey plugin

🎫 Bearer Tokens

JWT tokens for API authentication

bearer plugin

🏢 Organizations

Multi-tenant workspaces with roles

organization plugin

👑 Admin Functions

Administrative user management

admin plugin

Environment Variables Configuration

Core Requirements: At minimum, you need BETTER_AUTH_SECRET and BETTER_AUTH_URL to get authentication working.

Core Authentication Controls

bash

# Better Auth Core
BETTER_AUTH_SECRET="your-secret-key"
BETTER_AUTH_URL="http://localhost:3000"
BETTER_AUTH_TRUSTED_ORIGINS="http://localhost:3000"

# Email Features (required for magic link, verification, password reset)
RESEND_API_KEY="re_your_api_key"
EMAIL_FROM="noreply@yourdomain.com"

Feature Toggle Variables

bash

# Control which auth methods are available
NEXT_PUBLIC_AUTH_METHODS="credential,magiclink,google,github"
# Options: credential, magiclink, google, github, facebook, apple

bash

# Email verification
NEXT_PUBLIC_BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=true

# Password management
NEXT_PUBLIC_BETTER_AUTH_CHANGE_PASSWORD=true
NEXT_PUBLIC_BETTER_AUTH_CHANGE_EMAIL=true

# Two-Factor Authentication
NEXT_PUBLIC_BETTER_AUTH_2FA_ENABLE=true
NEXT_PUBLIC_BETTER_AUTH_2FA_SKIP_VERIFICATION_ON_ENABLE=true

# API Key management
NEXT_PUBLIC_BETTER_AUTH_TOKEN_MANAGEMENT=true

bash

# Google OAuth
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# GitHub OAuth
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Facebook OAuth
FACEBOOK_CLIENT_ID="your-facebook-app-id"
FACEBOOK_CLIENT_SECRET="your-facebook-app-secret"

# Apple OAuth
APPLE_CLIENT_ID="your-apple-service-id"
APPLE_CLIENT_SECRET="your-apple-private-key"

Organization & Billing

Billing Mode: Choose between individual user billing or organization-based billing.

bash

# Multi-tenant mode
NEXT_PUBLIC_BILLING_MODE="organization" # or "user"

# Available pages/features
NEXT_PUBLIC_ENABLED_PAGES="organization,invitation,account,settings,subscription,notifications,admin"

Quick Configuration Examples

Minimal Setup (Email/Password only)

bash

BETTER_AUTH_SECRET="your-secret"
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_AUTH_METHODS="credential"
NEXT_PUBLIC_BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=false

Full Features Setup

bash

# Core
BETTER_AUTH_SECRET="your-secret"
BETTER_AUTH_URL="http://localhost:3000"

# Email service
RESEND_API_KEY="re_your_key"
EMAIL_FROM="noreply@yourdomain.com"

# All auth methods
NEXT_PUBLIC_AUTH_METHODS="credential,magiclink,google,github"

# All user features
NEXT_PUBLIC_BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=true
NEXT_PUBLIC_BETTER_AUTH_2FA_ENABLE=true
NEXT_PUBLIC_BETTER_AUTH_TOKEN_MANAGEMENT=true

# Social providers
GOOGLE_CLIENT_ID="your-google-id"
GOOGLE_CLIENT_SECRET="your-google-secret"
GITHUB_CLIENT_ID="your-github-id"
GITHUB_CLIENT_SECRET="your-github-secret"

File Structure & User Pages

All authentication features are organized in dedicated route groups and component folders for easy navigation and maintenance.

📁 Authentication Routes

Location: src/app/[locale]/(auth)/

All public authentication pages grouped under a dedicated layout.

src/app/[locale]/(auth)/
├── login/                        # Login page with all methods
├── register/                     # User registration
├── logout/                       # Logout confirmation
├── reset-password/               # Password reset form
└── verify-request/               # Email & 2FA verification
    ├── totp/                     # TOTP verification
    ├── otp/                      # OTP verification
    └── recovery/                 # Recovery codes verification

🧩 Authentication Components

Location: src/components/features/auth/

Reusable authentication form components used across all auth pages.

src/components/features/auth/
└── forms/                        # All authentication forms
    ├── login.tsx                 # Main login form
    ├── credential-form.tsx       # Email/password form
    ├── magic-link-form.tsx       # Magic link form
    ├── register-form.tsx         # Registration forms
    └── recovery-code-form.tsx    # 2FA recovery form

👤 User Account Management

Location: src/app/[locale]/(app)/account/

Protected pages requiring user authentication. Access controlled by auth middleware.

src/app/[locale]/(app)/account/
├── settings/                     # Profile & security settings
├── api-keys/                     # API key management
├── subscription/                 # Subscription management
├── notifications/                # Notification preferences
├── organizations/                # Organization management
│   └── [id]/                     # Organization details & settings
└── invitations/                  # Organization invitations
    └── [id]/                     # Accept/decline invitations