GoTrue - Supabase's Auth Server

GoTrue is the auth server that powers Supabase. It handles user registration, login, JWT tokens, and session management. Originally built by Netlify, now maintained by Supabase. You can find the complete API documentation and self-hosting guide in their docs.

Here's the real shit: it works well with PostgreSQL's Row Level Security, which is actually useful unlike most auth integrations that require you to roll your own access control.

What GoTrue Actually Does

JWT Token Handling: Issues standard JWT tokens that don't randomly break like some auth services I won't name. Configurable expiration, custom claims for RBAC. The tokens actually work.

Authentication Methods:

• Email/password (with sane password policies you can actually configure)
• Magic links (passwordless login that works most of the time)
• OAuth with 20+ providers - Google, GitHub, Apple, Discord, etc.
• SMS OTP (when your SMS provider isn't down)
• Anonymous sessions for guest users

PostgreSQL Integration: This is where GoTrue shines. It integrates with PostgreSQL's Row Level Security so you can do access control at the database level instead of writing brittle application logic.

-- Users can only see their own data - enforced by the database
CREATE POLICY "users_own_data" ON profiles 
  FOR ALL USING (auth.uid() = user_id);

-- Different levels of access
CREATE POLICY "users_read_public" ON profiles 
  FOR SELECT USING (is_public = true);

-- Time-based access control
CREATE POLICY "users_edit_recent" ON posts 
  FOR UPDATE USING (
    auth.uid() = user_id 
    AND created_at > now() - interval '1 hour'
  );

The auth.uid() function extracts the user ID from the JWT automatically. No more checking tokens in your application code. But here's the magic: this happens at the database level, so even if your application has bugs, users can't access data they shouldn't see. It's like having a security guard at every table.

Real-World Architecture

GoTrue is a stateless Go service that connects to PostgreSQL. In production, you'll want:

• Multiple GoTrue instances behind a load balancer (because shit breaks)
• PostgreSQL connection pooling with PgBouncer or similar
• Proper monitoring because you'll need it when things go wrong
• Rate limiting configured properly (default limits are too permissive)

The service works with PostgREST for API generation and Realtime for WebSockets. You can also integrate with PgBouncer for connection pooling and Prometheus for monitoring. Check out the production architecture examples and customer case studies for real-world implementations.

Cost Reality Check

Here's what you'll actually pay as of September 2025 (and why your CFO will either love you or fire you):

Supabase (includes GoTrue):

• Free: 50,000 MAU (good for prototypes)
• Pro: $25/month for 100,000 MAU
• Overage: $0.00325 per MAU

Auth0:

• Essentials: $35/month for 500 MAU (already expensive for a side project)
• Professional: $240/month for 1,000 MAU (starts hurting real quick)
• Enterprise: $23,000+ annually (Auth0 hit us with some massive unexpected bill, think it was like $3,000 or something crazy, turns out they were counting password resets as active users which is complete bullshit)

Firebase Auth: Google's pricing calculator is designed to confuse you, but expect $150-300/month for 100K MAU.

Self-Hosting vs Managed

Self-hosting benefits:

• Your data stays on your servers
• No vendor lock-in bullshit
• Deploy wherever you want
• Customize everything

Self-hosting downsides:

• You're responsible for security updates
• No SLA unless you build it yourself
• Monitoring and alerting is your problem
• When it breaks at 3am, you fix it

Managed service benefits:

• Supabase handles the operational stuff
• 99.9% uptime SLA (when it works)
• Built-in monitoring and logs
• Someone else gets called at 3am

Some companies like Mobbin and Good Tape migrated from Firebase/Auth0 to save money. Read the migration guides and check out discussions on Hacker News for real migration experiences. Also see Reddit discussions where developers share their experiences with costs and complexity.

But before you get excited about the cost savings, you need to understand how GoTrue stacks up against the competition. Let's compare the real differences.

Getting Started - The Easy Part

Use Supabase's managed service unless you hate money and love operational headaches. It works and they handle the boring stuff.

// Basic setup that actually works
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://your-project.supabase.co',
  'your-anon-key'
)

// User registration
const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'secure-password'
})

Self-hosting for masochists and enterprises with compliance requirements:

## Basic Docker setup - will probably work
FROM supabase/gotrue:latest

ENV GOTRUE_SITE_URL=https://yourapp.com
ENV GOTRUE_JWT_SECRET=your-256-bit-secret-that-you-actually-need-to-generate
ENV DATABASE_URL=postgresql://user:pass@db:5432/auth

EXPOSE 9999
CMD ["gotrue"]

Configuration That Won't Bite You

Security settings you actually need:

## JWT config - get this wrong and everything breaks
GOTRUE_JWT_SECRET=your-256-bit-secret-not-password123
GOTRUE_JWT_EXP=3600  # 1 hour - don't make it too long
GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED=true

## Rate limiting - defaults are way too generous
GOTRUE_RATE_LIMIT_EMAIL_SENT=10  # Not 60, trust me
GOTRUE_RATE_LIMIT_HEADER=X-Forwarded-For

## SMTP - will break randomly
GOTRUE_SMTP_HOST=smtp.sendgrid.net
GOTRUE_SMTP_PORT=587
GOTRUE_SMTP_USER=apikey
GOTRUE_SMTP_PASS=your-sendgrid-api-key

Production gotchas:

• JWT rotation fucked us for weeks. Think it was iOS caching tokens but honestly we tried everything - clearing storage, force logout, even had users reinstall the app. Finally figured out we needed some rollback strategy but by then everyone was pissed (JWT rotation best practices)
• Email delivery fails silently with error messages like "SMTP Error 550" - helpful, right? (SMTP troubleshooting guide)
• PostgreSQL connection limits will kill you at scale (learned this during a product launch when everything went down) (PostgreSQL connection management)
• Docker health checks need manual configuration or your load balancer will route traffic to dead containers (Docker health check docs)

PostgreSQL RLS - The Good Part

This is why you'd choose GoTrue over other options. Database-level security that actually works:

-- Enable RLS - forget this and your data is wide open
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

-- Users see only their data
CREATE POLICY \"users_own_profiles\" ON profiles
  FOR ALL USING (auth.uid() = user_id);

-- Admin access (write this policy carefully)
CREATE POLICY \"admins_all_access\" ON profiles
  FOR ALL USING (
    (auth.jwt() ->> 'app_metadata')::json ->> 'role' = 'admin'
  );

RLS gotchas:

• Locked myself out of prod DB with a bad admin policy at 2am. Had to restore from backup because I'm an idiot (RLS policy debugging guide)
• Performance tanks with complex policies - our user lookup went from maybe 50ms to like 800ms or some shit, took forever to debug (RLS performance optimization)
• Debugging policy problems is hell - PostgreSQL error messages are cryptic as fuck (PostgreSQL RLS troubleshooting)
• Migration scripts break everything if you forget to disable RLS first. Cost us maybe 3-4 hours of downtime, customers were not happy (RLS migration strategies)

Production Architecture That Won't Fall Over

## docker-compose.yml - actually tested in production
version: '3.8'
services:
  gotrue-1:
    image: supabase/gotrue:latest
    environment:
      - GOTRUE_DB_MAX_POOL_SIZE=20  # Not 50, you'll run out of connections
    deploy:
      replicas: 2  # Start small
  
  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=auth
      - POSTGRES_PASSWORD=secure-password
      - POSTGRES_MAX_CONNECTIONS=200  # You'll need this
    volumes:
      - postgres_data:/var/lib/postgresql/data

Load balancer setup (because you'll need it):

upstream gotrue_backend {
    server gotrue-1:9999;
    server gotrue-2:9999;
    # Health checks are manual - Docker health checks don't work well
}

server {
    listen 443 ssl;
    server_name auth.yourapp.com;
    
    location /health {
        proxy_pass http://gotrue_backend;
        proxy_connect_timeout 5s;
        proxy_read_timeout 10s;
    }
    
    location / {
        proxy_pass http://gotrue_backend;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Monitoring Because You'll Need It

## Basic monitoring setup
GOTRUE_METRICS_ENABLED=true
GOTRUE_METRICS_EXPORTER=prometheus
OTEL_EXPORTER_PROMETHEUS_PORT=9100

What to monitor (from painful experience):

• PostgreSQL connection count (maxed out at like 100 connections during a traffic spike, everything died) (PostgreSQL monitoring guide)
• Email send failures (SendGrid went down for hours and we had no backup, users couldn't sign up) (Email monitoring best practices)
• JWT validation errors (mobile clients don't refresh tokens properly - expect like 5-10% error rate, it's annoying) (JWT monitoring patterns)
• Memory usage (Go garbage collector spikes to 2GB then drops to 200MB - scared the shit out of us the first time) (Go memory profiling)
• Response times for /token endpoint (went from 50ms to 2s when we hit connection limits, users noticed) (API performance monitoring)

Prometheus Monitoring: Essential for production GoTrue deployments

Framework Integration Gotchas

Next.js with Auth Helpers:

// This works but SSR is tricky
import { createBrowserSupabaseClient } from '@supabase/auth-helpers-nextjs'
import { SessionContextProvider } from '@supabase/auth-helpers-react'

export default function App({ Component, pageProps }) {
  const supabaseClient = createBrowserSupabaseClient()
  
  return (
    <SessionContextProvider supabaseClient={supabaseClient}>
      <Component {...pageProps} />
    </SessionContextProvider>
  )
}

Common problems:

• Token refresh during SSR breaks things (NextJS 13.4+ has a specific bug with middleware) (Next.js auth middleware debugging)
• Hydration mismatches with auth state (you get "Warning: Text content did not match" in dev tools) (React hydration troubleshooting)
• Mobile Safari cookie issues (SameSite=None stopped working in iOS 16.4, had to add a user-agent check) (Safari cookie debugging guide)

React Native has its own special hell:

import { createClient } from '@supabase/supabase-js'
import AsyncStorage from '@react-native-async-storage/async-storage'

const supabase = createClient(url, anonKey, {
  auth: {
    storage: AsyncStorage,
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: false  // Important for mobile
  }
})

Security - Don't Fuck This Up

JWT secrets - get this wrong and you're fucked:

## Generate a proper secret
openssl rand -base64 32

## Use a secrets manager in production
GOTRUE_JWT_SECRET=$(aws ssm get-parameter --name \"/auth/jwt-secret\" --with-decryption --query Parameter.Value --output text)

HTTPS everywhere - GoTrue sends tokens in headers:

## Redirect all HTTP to HTTPS
server {
    listen 80;
    server_name auth.yourapp.com;
    return 301 https://$server_name$request_uri;
}

Database security:

## Always use SSL
DATABASE_URL=postgresql://user:pass@host:5432/db?sslmode=require

Production lessons learned:

• Connection pool exhaustion takes down everything (Connection pooling strategies)
• JWT rotation breaks mobile apps for weeks (Mobile JWT handling patterns)
• Email templates break on HTML updates (Email template best practices)
• Rate limiting triggers on legitimate traffic during launches (Rate limiting patterns)
• CORS configuration will waste hours of your life (CORS troubleshooting guide)

The architecture works well once you get through the pain of initial setup. Just don't expect it to be as simple as the docs make it look. For real production examples, check Supabase's scaling blog posts, the community examples repo, and Docker deployment guides. Also useful: Terraform provider docs and Kubernetes manifests from the community.

At this point, you probably have questions. Good. So did we when we first deployed GoTrue. Here are the answers to the questions you're actually going to ask (not the ones in the official docs).