GoTrue Authentication Server - AI-Optimized Technical Reference

Overview

GoTrue is Supabase's open-source authentication server that integrates directly with PostgreSQL. Originally built by Netlify, now maintained by Supabase. MIT licensed, designed to replace expensive enterprise auth services.

Core Functionality

What GoTrue Does:

• JWT token management with RFC 7519 compliance
• User registration, login, session management
• PostgreSQL Row Level Security (RLS) integration
• OAuth with 20+ providers (Google, GitHub, Apple, Discord)
• Email/password, magic links, SMS OTP, anonymous sessions

Cost Analysis (September 2025)

Service	100K MAU Cost	Notes
GoTrue (Supabase)	$25/month	$0.00325 per additional MAU
Auth0 Professional	$240/month	Surprise billing for password resets
Firebase Auth	$150-300/month	Hidden costs in Google's calculator
AWS Cognito	$275+/month	Complex pricing structure

Self-hosting costs: $20-50/month for small apps, plus operational overhead.

Critical Production Configuration

Database Integration - The Killer Feature

-- Enable RLS - FORGET THIS AND DATA IS WIDE OPEN
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

-- User data isolation
CREATE POLICY "users_own_data" ON profiles 
  FOR ALL USING (auth.uid() = user_id);

-- Admin escape hatch (TEST THIS CAREFULLY)
CREATE POLICY "admin_access" ON profiles 
  FOR ALL USING (
    (auth.jwt() ->> 'app_metadata')::json ->> 'role' = 'admin'
  );

Essential Configuration Settings

# JWT - GET THIS WRONG AND EVERYTHING BREAKS
GOTRUE_JWT_SECRET=your-256-bit-secret-not-password123
GOTRUE_JWT_EXP=3600  # 1 hour max
GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED=true

# Rate limiting - DEFAULTS ARE TOO GENEROUS
GOTRUE_RATE_LIMIT_EMAIL_SENT=10  # Not 60
GOTRUE_RATE_LIMIT_HEADER=X-Forwarded-For

# Database connections - WILL KILL YOU AT SCALE
GOTRUE_DB_MAX_POOL_SIZE=20  # Not 50
DATABASE_URL=postgresql://user:pass@host:5432/db?sslmode=require

Production Architecture Requirements

Minimum System Requirements That Work

Development: 1 vCPU, 512MB RAM
Production: 2+ vCPU, 2GB+ RAM per instance, PostgreSQL with PgBouncer connection pooling

Load Balancer Configuration

upstream gotrue_backend {
    server gotrue-1:9999;
    server gotrue-2:9999;
}

server {
    listen 443 ssl;
    location / {
        proxy_pass http://gotrue_backend;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_connect_timeout 5s;
        proxy_read_timeout 10s;
    }
}

Critical Failure Modes and Solutions

Authentication Failures

• JWT rotation breaks mobile apps for weeks - iOS caches tokens, requires rollback strategy
• Token refresh fails silently - Network issues during refresh force logout
• Different behavior between web and mobile - Always test both platforms

Database Issues

• Connection pool exhaustion kills everything - Monitor PostgreSQL connection count
• RLS policies tank performance - 3-table join policies: 100ms → 3 seconds
• Migration scripts break with RLS enabled - Use SET ROLE to bypass RLS during migrations

Email Delivery

• SMTP fails silently with "Error 550" - No helpful error messages
• All SMTP providers have outages - Require backup plan
• Email templates break on HTML updates - Test thoroughly

Operational Gotchas

• Docker health checks need manual configuration - Load balancer routes to dead containers
• Go garbage collector spikes: 200MB → 2GB → 200MB - Normal but scary
• Memory usage monitoring essential - Expect 5-10% JWT validation error rate from mobile clients

Framework Integration Pain Points

Next.js

// SSR auth state is tricky
import { createBrowserSupabaseClient } from '@supabase/auth-helpers-nextjs'

// Common issues:
// - Token refresh during SSR breaks (NextJS 13.4+ middleware bug)
// - Hydration mismatches with auth state
// - Mobile Safari cookie issues (SameSite=None broken in iOS 16.4)

React Native

const supabase = createClient(url, anonKey, {
  auth: {
    storage: AsyncStorage,
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: false  // IMPORTANT FOR MOBILE
  }
})

// Issues: Deep linking works 80% of time, AsyncStorage can corrupt session data

Security Requirements

Production Security Checklist

• Generate proper JWT secrets: openssl rand -base64 32
• HTTPS everywhere - GoTrue sends tokens in headers
• Use secrets manager - Never hardcode JWT secrets
• Database SSL required: DATABASE_URL=...?sslmode=require
• CORS configuration - Will waste hours debugging

Monitoring Requirements

Essential Alerts

• Database connection exhaustion (kills everything)
• Authentication failure rate spikes
• Email delivery failures
• Memory/CPU usage spikes
• /token endpoint response times (bottleneck)

Prometheus Configuration

GOTRUE_METRICS_ENABLED=true
GOTRUE_METRICS_EXPORTER=prometheus
OTEL_EXPORTER_PROMETHEUS_PORT=9100

Migration Realities

From Auth0/Firebase

What transfers: User emails, metadata, custom claims
What doesn't: Hashed passwords (security requirement)
Reality: All users must reset passwords, expect support tickets and complaints

Migration Strategy

• Export user data first
• Run dual auth systems temporarily
• Force password resets gradually
• Send discount codes to soften impact

Multi-Tenancy Implementation

-- Tenant isolation at database level
CREATE POLICY "tenant_isolation" ON user_data
  FOR ALL USING (
    tenant_id = (auth.jwt() ->> 'app_metadata')::json ->> 'tenant_id'
  );

Approaches:

• Separate databases per tenant (expensive)
• RLS policies with tenant ID (complex)
• JWT claims with organization data (requires careful design)

SMTP Provider Reliability

Recommended Providers

• SendGrid: Usually works, decent free tier
• AWS SES: Cheap for volume, requires AWS setup
• Postmark: Expensive but very reliable
• Mailgun: Good APIs, reasonable pricing

All providers have outages - plan accordingly

Backup and GDPR Compliance

# Encrypted backup for compliance
pg_dump -h localhost -U postgres -d auth_db | gzip | gpg --encrypt > backup.sql.gz.gpg

GDPR Requirements:

• Encrypt backups containing user data
• Implement data retention policies
• Support user data deletion requests
• Log backup access

Serverless Compatibility

Works but requires:

• PgBouncer or Supabase pooler (mandatory)
• Proper secret management
• Cold start latency consideration
• Connection pooling configuration

Support and Resources Quality Assessment

Reliable Resources:

• GoTrue GitHub repo (read when docs fail)
• Supabase Discord (real humans with solutions)
• RLS Tutorial (actually useful)
• Stack Overflow Supabase tags

Optimistic Resources:

• Self-hosting guide (makes it look easier than reality)
• Migration guides (missing angry customer management)
• Framework examples (skip edge cases)

Decision Criteria

Choose GoTrue When:

• Cost is primary concern ($25 vs $240+ monthly)
• You want PostgreSQL integration
• Data ownership is important
• Open source/no vendor lock-in required

Choose Enterprise Auth When:

• Need SOC2/ISO certifications
• Require enterprise SSO integrations
• Want comprehensive compliance features
• $23,000+ annually is acceptable

Self-Host When:

• Data must stay on your servers
• Custom compliance requirements
• You have operational expertise
• Can handle 3am outages

Use Managed Service When:

• Want 99.9% SLA
• Don't want operational overhead
• Need built-in monitoring
• Prefer predictable costs

Performance Benchmarks

• Normal response time: 50ms for token endpoint
• Connection limit impact: 50ms → 2 seconds when maxed
• RLS policy impact: Simple policies add 10-20ms, complex join policies add 700ms+
• Expected JWT error rate: 5-10% from mobile clients (normal)
• Memory usage pattern: 200MB baseline, 2GB GC spikes (normal)

Breaking Points

• PostgreSQL connection limits: Monitor constantly, will kill everything
• Email rate limiting: Default 60/hour too high, use 10/hour
• JWT secret rotation: Mobile apps break for weeks
• RLS policy complexity: Performance degrades exponentially
• SMTP provider outages: Always have backup configured