Credentials Authentication

Email/password authentication is always available in the boilerplate and works out-of-the-box with just basic configuration.

Quick Start

Minimum setup: Only BETTER_AUTH_SECRET and BETTER_AUTH_URL required for basic login/register to work.
# Essential configuration
BETTER_AUTH_SECRET="your-super-secret-key"
BETTER_AUTH_URL="http://localhost:3000"
That's it! Users can now register and login at /[locale]/login and /[locale]/register.

Environment Variables

Core Authentication

# Required - Better Auth core
BETTER_AUTH_SECRET="generate-with-openssl-rand-base64-32"
BETTER_AUTH_URL="http://localhost:3000"

# Optional - Email service (needed for verification & password reset)
RESEND_API_KEY="re_your_resend_api_key"
EMAIL_FROM="noreply@yourdomain.com"

Feature Controls

# Require email verification before login
NEXT_PUBLIC_BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=true
Impact:
  • true = Users must click email link before they can login
  • false = Users can login immediately after registration (default)

User Pages & Components

Authentication Pages

Location: All authentication pages are in src/app/[locale]/(auth)/
Registration: /[locale]/register
  • Email validation and password strength checking
  • Password confirmation matching
  • Social auth options (if configured)
  • Automatic redirect after success
Registration form with name, email, password fields and social auth options Login: /[locale]/login
  • Email/password form
  • "Forgot password?" link
  • Social auth options (if configured)
Login form with email/password fields and social auth options Password Reset: /[locale]/reset-password
  • Email input to request reset
  • New password form (when using reset link)
Email Verification: /[locale]/verify-request
  • Shows verification status
  • "Resend email" button
  • Success/error messages

Account Management Pages

Location: User account pages are in src/app/[locale]/(app)/account/
Account Settings: /[locale]/account/settings
  • Profile information (name, avatar)
  • Email change (if CHANGE_EMAIL=true)
  • Password change (if CHANGE_PASSWORD=true)
Email Change Interface: Email change interface in account settings Password Change Interface: Password change interface in account settings Notifications: /[locale]/account/notifications
  • Email preferences
  • Security notifications

Registration & Login Flows

The login form shows all available authentication methods, including the email/password credentials at the bottom of the form.

With Email Verification (Recommended)

1

User registers

  • Visits /[locale]/register
  • Fills email/password form
  • Account created but emailVerified: null
2

Verification email sent

  • User redirected to /[locale]/verify-request
  • Email with verification link sent automatically
  • Cannot login until verified
3

Email verified

  • User clicks link in email
  • Account marked as verified
  • Can now login normally

Without Email Verification (Simplified)

NEXT_PUBLIC_BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=false
  • User registers → immediately logged in
  • Direct redirect to account dashboard
  • No email verification required

Password Features

Built-in Password Requirements

The boilerplate enforces these rules automatically:
  • Minimum 8 characters
  • Must contain letters and numbers
  • Cannot be common passwords
  • Real-time validation feedback

Password Reset Flow

1

Request reset

  • User clicks "Forgot password?" on login page
  • Enters email address
  • Rate limited: 1 request per 5 minutes
2

Reset email

  • Secure reset link sent (expires in 1 hour)
  • One-time use token
  • Clear instructions included
3

Set new password

  • User clicks link → new password form
  • Same validation rules apply
  • All sessions invalidated for security

Change Password (Logged-in)

Where: /[locale]/account/settings Requirements:
  • Current password verification
  • New password meets strength requirements
  • Cannot be same as current password
Password change requires NEXT_PUBLIC_BETTER_AUTH_CHANGE_PASSWORD=true

Email Templates

The boilerplate includes pre-built templates: Email Verification
  • Clean design with clear call-to-action
  • Expires in 1 hour
  • Customizable via notification service
Password Reset
  • Security-focused messaging
  • One-time use warning
  • Expiration time clearly stated
Email Change
  • Both old and new email notified
  • Confirmation required
  • Rollback available if not verified

Security Features

Built-in Protections

Rate Limiting
  • Prevents brute force attacks
  • Failed login attempt tracking
  • Cooldown periods for repeated failures
Session Security
  • Secure HTTP-only cookies
  • CSRF protection on all forms
  • XSS prevention built-in
Active Sessions Management: Active sessions management interface Password Security
  • bcrypt hashing (industry standard)
  • Secure token generation
  • Session invalidation on password change

Common Issues & Solutions

Users can't login after registration?Check if email verification is enabled but emails aren't being sent:
  • Verify RESEND_API_KEY is set
  • Check EMAIL_FROM domain is verified in Resend
  • Look in spam/junk folders
Password reset emails not arriving?
  • Ensure RESEND_API_KEY is configured
  • Check if BETTER_AUTH_URL matches your domain
  • Verify reset link hasn't expired (1 hour limit)
Rate limiting issues?
  • Clear browser cookies/data
  • Wait for cooldown period
  • Check if IP is being shared (development environments)

Testing Checklist

1

Registration

  1. Go to /[locale]/register
  2. Test with valid email you can access
  3. Verify password strength validation
  4. Complete registration flow
2

Email Verification

  1. Check for verification email (if enabled)
  2. Click verification link
  3. Confirm account is activated
  4. Test login with new credentials
3

Password Features

  1. Test "Forgot password?" flow
  2. Change password in account settings
  3. Test login with new password
  4. Verify old sessions are handled correctly
All working? Users can now register, verify emails, login, and manage their passwords using the built-in pages and forms.
    Credentials Authentication | ShipSaaS Documentation | ShipSaaS - Launch your SaaS with AI in days