---

name: supabase-auth description: Setup and manage Supabase authentication including project connection, tokens, login methods, and user management. Use when configuring Supabase access, implementing authentication, or managing users.

Supabase Authentication Skill

Setup and manage Supabase authentication for projects.

Quick Reference

Environment Variables

Copy# Required for all Supabase operations
SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# For server-side admin operations (NEVER expose client-side)
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# For CI/CD pipelines
SUPABASE_ACCESS_TOKEN=<personal-access-token>
SUPABASE_DB_PASSWORD=<database-password>
SUPABASE_PROJECT_ID=<project-ref>

Client Initialization

Browser/Client-Side

Copyimport { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_ANON_KEY
)

Server-Side (with Service Role)

Copyimport { createClient } from '@supabase/supabase-js'

const supabaseAdmin = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_SERVICE_ROLE_KEY,
  {
    auth: {
      autoRefreshToken: false,
      persistSession: false
    }
  }
)

Authentication Methods

Email/Password

Copy// Sign up
const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'password123',
  options: {
    data: { full_name: 'John Doe' }  // user metadata
  }
})

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

// Sign out
const { error } = await supabase.auth.signOut()

Magic Link (Passwordless)

Copyconst { data, error } = await supabase.auth.signInWithOtp({
  email: 'user@example.com',
  options: {
    emailRedirectTo: 'https://yourapp.com/welcome'
  }
})

OAuth Providers

Copyconst { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'github',  // or 'google', 'discord', etc.
  options: {
    redirectTo: 'https://yourapp.com/auth/callback'
  }
})

Anonymous Auth

Copyconst { data, error } = await supabase.auth.signInAnonymously()

Session Management

Get Current Session

Copy// From local storage (fast, no network)
const { data: { session } } = await supabase.auth.getSession()

// Validate with server (secure, use on server-side)
const { data: { user } } = await supabase.auth.getUser()

Listen for Auth Changes

Copyconst { data: { subscription } } = supabase.auth.onAuthStateChange(
  (event, session) => {
    console.log(event, session)
    // Events: SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED
  }
)

// Cleanup
subscription.unsubscribe()

Password Recovery

Copy// Request reset
const { error } = await supabase.auth.resetPasswordForEmail(
  'user@example.com',
  { redirectTo: 'https://yourapp.com/update-password' }
)

// Update password (after redirect)
const { error } = await supabase.auth.updateUser({
  password: 'new_password'
})

Admin Operations (Server-Side Only)

Copy// Create user (bypasses email confirmation)
const { data, error } = await supabaseAdmin.auth.admin.createUser({
  email: 'user@example.com',
  password: 'password123',
  email_confirm: true,
  app_metadata: { role: 'admin' }
})

// Delete user
const { error } = await supabaseAdmin.auth.admin.deleteUser(userId)

// Update user
const { data, error } = await supabaseAdmin.auth.admin.updateUserById(
  userId,
  { app_metadata: { role: 'moderator' } }
)

// List users
const { data, error } = await supabaseAdmin.auth.admin.listUsers()

Security Notes

1. Never expose service role key - It bypasses Row Level Security
2. Use getUser() on server - Don't trust getSession() for authorization
3. Use app_metadata for roles - user_metadata is user-editable
4. Enable RLS on all tables - Without it, anyone can access data

References

• auth-methods.md - All authentication methods in detail
• session-management.md - Session lifecycle and tokens
• mfa-setup.md - Multi-factor authentication