Authentication

KwikSaaS uses Supabase Auth for secure, session-based authentication. This guide covers setup, configuration, and customization of all auth flows.

Auth is pre-configured out of the box. This guide helps you understand and customize the implementation.

What’s Included

Email/password — Sign up with email verification, sign in, and password management
OAuth providers — Pre-configured Google and GitHub sign-in
Magic links — Passwordless authentication via email
Password reset — Secure reset flow with email confirmation
Protected routes — Middleware-based route protection
Session management — Server and client-side session handling

Prerequisites

Before configuring auth, ensure you have:

Supabase project

Create a project at supabase.com. You’ll need the project URL and anon key.

Environment variables

Copy .env.example to .env.local and fill in:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=eyJ...
SUPABASE_SECRET_KEY=eyJ...

Configure Supabase URLs

This step is critical. Auth flows will fail without correct URL configuration.

Go to Supabase Dashboard → Authentication → URL Configuration:

Setting	Value
Site URL	`http://localhost:3000` (dev) or `https://yourdomain.com` (prod)
Redirect URLs	`http://localhost:3000/auth/callback`

For production, add all domains:

https://yourdomain.com/auth/callback
https://www.yourdomain.com/auth/callback

OAuth Providers

Google OAuth

Create OAuth credentials

Go to Google Cloud Console
Create a new project or select existing
Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
Select Web application
Add authorized redirect URI from Supabase (found in provider settings)

Enable in Supabase

Go to Authentication → Providers → Google
Enable the provider
Enter Client ID and Client Secret from Google
Save changes

GitHub OAuth

Create OAuth App

Go to GitHub Settings → Developer settings → OAuth Apps
Click New OAuth App
Set Homepage URL to your site
Set Authorization callback URL from Supabase

Enable in Supabase

Go to Authentication → Providers → GitHub
Enable and enter Client ID and Client Secret
Save changes

Test OAuth by clicking the Google/GitHub buttons on /sign-in. You should be redirected to the provider and back to your dashboard.

Auth Flows

Magic Link Flow

User enters email on /sign-in
Server action calls supabase.auth.signInWithOtp()
User receives email with magic link
Click redirects to /auth/callback
Session is created and user lands on dashboard

Password Reset Flow

User clicks “Forgot password” → /forgot-password
Enter email, server action sends reset email
Email contains link to /reset-password?code=...
/auth/callback sets recovery cookie and redirects
User enters new password on /reset-password

File Structure

src/app/(auth)/
├── actions.ts              # Server actions for all auth operations
├── layout.tsx              # Auth layout wrapper
├── sign-in/page.tsx        # Sign in form
├── sign-up/page.tsx        # Sign up form
├── forgot-password/page.tsx # Request password reset
└── reset-password/page.tsx  # Set new password

src/app/auth/
└── callback/route.ts       # Handles all auth redirects

src/components/auth/
├── auth-page-layout.tsx    # Consistent auth page styling
├── oauth-buttons.tsx       # Google/GitHub sign-in buttons
└── update-password-form.tsx # Password reset form

src/lib/supabase/
├── client.ts               # Browser client
├── server.ts               # Server component client
├── admin.ts                # Admin client (service role)
└── middleware.ts           # Session refresh middleware

Protected Routes

Middleware in src/lib/supabase/middleware.ts handles route protection:

Unauthenticated users → Redirected away from /dashboard/*
Authenticated users → Redirected away from /sign-in, /sign-up, /forgot-password (unless in recovery mode)

Adding New Protected Routes

To protect additional routes, update the middleware patterns:

// In middleware.ts
const protectedPaths = ["/dashboard", "/settings", "/your-new-route"];

Auth Context

Access user state anywhere in your app:

import { useAuth } from "@/components/auth/auth-context";

function MyComponent() {
  const { user, session, loading, signOut } = useAuth();

  if (loading) return <Spinner />;
  if (!user) return <SignInPrompt />;

  return <div>Welcome, {user.email}</div>;
}

The AuthProvider wraps the app in layout.tsx and:

Listens to Supabase auth state changes
Identifies users in PostHog (if configured)
Provides signOut helper

Server Actions

All auth operations use server actions in src/app/(auth)/actions.ts:

Action	Purpose
`signIn`	Email/password sign in
`signUp`	Create new account
`signInWithMagicLink`	Send magic link email
`signInWithOAuth`	Initiate OAuth flow
`sendPasswordResetEmail`	Request password reset
`resetPassword`	Set new password
`signOut`	End session

All actions are rate-limited and return sanitized errors.

Email Templates

Auth emails are sent via Resend (if configured) or Supabase’s default SMTP.

Configure Resend (Recommended)

Set environment variables

RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=auth@yourdomain.com
RESEND_LOGO_URL=https://yourdomain.com/logo.png

Verify your domain

Add SPF, DKIM, and DMARC records in your DNS provider as shown in Resend dashboard.

Connect to Supabase

Go to Supabase → Authentication → Email Templates → SMTP Settings and enter Resend SMTP credentials.

Email Template Files

Custom React Email templates are in src/components/emails/:

MagicLinkEmail.tsx
ConfirmEmailTemplate.tsx
ResetPasswordEmail.tsx

Troubleshooting

OAuth redirect fails

Check Supabase URL Configuration:

Site URL must match your app URL exactly
Redirect URLs must include /auth/callback
For local dev, use http://localhost:3000, not 127.0.0.1

Verify OAuth credentials:

Client ID and Secret are correct
Redirect URI in provider console matches Supabase

Email verification not arriving

Check: 1. Spam/junk folder 2. Supabase rate limits (4 emails/hour on free tier) 3. Email templates are enabled in Supabase dashboard 4. If using Resend, verify domain is confirmed

Session not persisting

Possible causes: - Cookies blocked by browser - NEXT_PUBLIC_SITE_URL doesn’t match actual URL - Middleware not running (check middleware.ts matcher)

Reset password shows error

Recovery flow requires:

Valid reset link (not expired)
Recovery cookie set by /auth/callback
Correct type=recovery in callback URL

Next Steps

Payments

Add Stripe billing after auth is working

Dashboard

Customize the protected dashboard pages

Getting Started

Deployment

Architecture

Reference

Authentication

Authentication

What’s Included

Prerequisites

Configure Supabase URLs

OAuth Providers

Google OAuth

GitHub OAuth

Auth Flows

Magic Link Flow

Password Reset Flow

File Structure

Protected Routes

Adding New Protected Routes

Auth Context

Server Actions

Email Templates

Configure Resend (Recommended)

Email Template Files

Troubleshooting

Next Steps

Payments

Dashboard

​Authentication

​What’s Included

​Prerequisites

​Configure Supabase URLs

​OAuth Providers

​Google OAuth

​GitHub OAuth

​Auth Flows

​Sign Up Flow

​Magic Link Flow

​Password Reset Flow

​File Structure

​Protected Routes

​Adding New Protected Routes

​Auth Context

​Server Actions

​Email Templates

​Configure Resend (Recommended)

​Email Template Files

​Troubleshooting

​Next Steps

Payments

Dashboard

Authentication

What’s Included

Prerequisites

Configure Supabase URLs

OAuth Providers

Google OAuth

GitHub OAuth

Auth Flows

Sign Up Flow

Magic Link Flow

Password Reset Flow

File Structure

Protected Routes

Adding New Protected Routes

Auth Context

Server Actions

Email Templates

Configure Resend (Recommended)

Email Template Files

Troubleshooting

Next Steps