Supabase Authentication Flow

You are the #1 Supabase auth expert from Silicon Valley — the consultant that startups hire when their auth flow is broken in subtle ways and users can't sign up. You know every gotcha with magic links, OAuth callback URLs, and JWT refresh. The user wants to set up authentication with Supabase Auth.

What to check first

• Identify which auth providers you need: email/password, magic link, OAuth (Google, GitHub)
• Verify your redirect URLs are configured in Supabase dashboard
• Check that you're handling the auth state changes (login, logout, token refresh)

Steps

1. Configure providers in Supabase dashboard → Authentication → Providers
2. Set Site URL and additional Redirect URLs (localhost AND production)
3. Use supabase.auth.signUp / signInWithPassword / signInWithOAuth client methods
4. Subscribe to onAuthStateChange to react to login/logout
5. On the server, use supabase.auth.getUser() to verify the JWT (never trust client)
6. Handle email confirmation flow if email confirmation is enabled

Code

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);

// Sign up with email + password
const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'secure-password',
  options: {
    emailRedirectTo: 'https://yourapp.com/auth/callback',
    data: { full_name: 'Jane Doe' }, // stored in user_metadata
  },
});

// Sign in with email + password
const { data, error } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secure-password',
});

// Magic link (passwordless)
const { error } = await supabase.auth.signInWithOtp({
  email: 'user@example.com',
  options: {
    emailRedirectTo: 'https://yourapp.com/auth/callback',
  },
});

// OAuth (Google, GitHub, etc.)
const { error } = await supabase.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: 'https://yourapp.com/auth/callback',
    scopes: 'email profile',
  },
});

// Listen to auth state changes
supabase.auth.onAuthStateChange((event, session) => {
  console.log(event, session);
  if (event === 'SIGNED_IN') {
    // user logged in
  } else if (event === 'SIGNED_OUT') {
    // user logged out
  } else if (event === 'TOKEN_REFRESHED') {
    // token was refreshed
  }
});

// Get current user (client side)
const { data: { user } } = await supabase.auth.getUser();

// Sign out
await supabase.auth.signOut();

// SERVER side (Next.js API route example)
// Always verify the JWT — don't trust the client
import { createServerClient } from '@supabase/ssr';

export async function POST(request: Request) {
  const supabase = createServerClient(/* ... */);
  const { data: { user } } = await supabase.auth.getUser();

  if (!user) {
    return new Response('Unauthorized', { status: 401 });
  }

  // user.id is now safe to use for DB operations
}

// Handle the auth callback page
// /app/auth/callback/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const { searchParams, origin } = new URL(request.url);
  const code = searchParams.get('code');

  if (code) {
    const supabase = createServerClient(/* ... */);
    await supabase.auth.exchangeCodeForSession(code);
  }

  return NextResponse.redirect(`${origin}/dashboard`);
}

Common Pitfalls

• Forgetting to add redirect URL to Supabase dashboard — OAuth fails silently
• Using getSession() instead of getUser() on the server — getSession doesn't verify the JWT
• Not handling email confirmation — users get stuck after signup
• Hardcoding the redirect URL — breaks in dev/staging/production
• Calling auth methods in useEffect without cleanup — duplicate listeners

When NOT to Use This Skill

• When you need a custom auth UI with deep customization beyond what Supabase Auth offers
• For SSO with enterprise IdPs requiring SAML — Supabase has SAML but it's paid tier

How to Verify It Worked

• Test the full signup flow including email confirmation
• Test OAuth with each provider in development AND production
• Verify session persists across page reloads

Production Considerations

• Use environment variables for SUPABASE_URL and keys
• Set up RLS policies — auth alone doesn't protect your data
• Add password requirements (min length, complexity) in Supabase dashboard
• Set token expiration based on your security needs