• Overview
• Quick Start: Supabase Auth (Default)
• Quick Start: Local PostgreSQL Auth
• Architecture
• Database Schema
• Configuration Reference
• OAuth Setup
• Security Best Practices
• API Reference
• Comparison: Supabase vs Local PostgreSQL
• Migration Guide
• Troubleshooting

SynthStack implements a flexible authentication system that supports multiple providers through a unified abstraction layer. This allows you to choose the auth provider that best fits your deployment requirements without changing application code.

• Provider Abstraction - Switch auth providers via database config (no code changes)
• Enterprise Security - Argon2id password hashing (65536 memory cost)
• JWT Sessions - Access tokens (1h) + refresh tokens (7d) with rotation
• OAuth Support - Google, GitHub, Discord, Microsoft social login (both Supabase and Local)
• Auto-Detection - Automatically uses local auth when Supabase is not configured
• Account Protection - Lockout after failed attempts, email verification
• Session Management - Token families detect reuse attacks
• Audit Trail - Login history, IP tracking, device identification

• Auth Provider Wizard - Pick Supabase vs Local
• Supabase Auth Setup - Recommended path (OAuth)
• Local Auth Setup - Fully self-hosted (OAuth supported)

Recommended for: Most users, fastest setup, managed service

1. Sign up at https://supabase.com
2. Create a new project
3. Wait for database provisioning (~2 minutes)

1. Navigate to Settings → API
2. Copy the following:
   • Project URL → SUPABASE_URL
   • anon/public key → SUPABASE_ANON_KEY
   • service_role key → SUPABASE_SERVICE_ROLE_KEY (secret!)

Add to your root .env:

SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
VITE_SUPABASE_URL=https://xxxxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Supabase is the default provider. To explicitly set it:

UPDATE auth_provider_config
SET
  active_provider = 'supabase',
  supabase_enabled = true;

1. In Supabase: Authentication → URL Configuration
   • Site URL: https://yourdomain.com
   • Redirect URLs: include https://yourdomain.com/** and http://localhost:3050/**
2. In Supabase: Authentication → Providers
   • Enable Google/GitHub/etc and paste client ID/secret

Guides:

• Supabase Auth Setup (Wizard)
• OAuth Setup (Supabase)

Done! Your app now uses Supabase authentication.

Recommended for: Self-hosted deployments, full data control, no external dependencies

Create a secure 256-bit secret for signing tokens:

openssl rand -base64 32

Copy the output (e.g., x3H7k9mP2vR5wQ8sL1nC4bF6tY0jU9iA3gD5hK7mN2q=)

Add to your root .env:

# Required for local auth
JWT_SECRET=x3H7k9mP2vR5wQ8sL1nC4bF6tY0jU9iA3gD5hK7mN2q=
DATABASE_URL=postgresql://user:password@localhost:5432/synthstack

# Optional: Remove Supabase vars if not using
# SUPABASE_URL=...
# SUPABASE_ANON_KEY=...
# SUPABASE_SERVICE_ROLE_KEY=...

Local auth tables are created by:

• services/directus/migrations/070_local_auth.sql
• services/directus/migrations/071_local_auth_schema_fix.sql

If you need to apply it manually:

docker compose exec -T postgres psql -U "${DB_USER:-synthstack}" -d "${DB_DATABASE:-synthstack}" < services/directus/migrations/070_local_auth.sql
docker compose exec -T postgres psql -U "${DB_USER:-synthstack}" -d "${DB_DATABASE:-synthstack}" < services/directus/migrations/071_local_auth_schema_fix.sql

Connect to your PostgreSQL database and run:

UPDATE auth_provider_config
SET
  active_provider = 'local',
  local_enabled = true,
  supabase_enabled = false;

Local auth can send verification/reset emails when your email provider is configured. If no email provider is configured, tokens are logged in the API output for development.

OAuth is supported for local auth via the service layer. Configure OAuth providers normally.

Next: Local Auth Setup (Wizard)

Done! Your app now uses local PostgreSQL authentication.

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (Vue)                          │
│                   apps/web/src/services/auth.ts                 │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    API Gateway (Fastify)                        │
│              packages/api-gateway/src/routes/auth.ts            │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Auth Service Layer                         │
│          packages/api-gateway/src/services/auth/index.ts        │
│                                                                 │
│   1. Reads auth_provider_config table                          │
│   2. Detects active provider                                   │
│   3. Routes requests to appropriate provider                   │
└────────────────────────────┬────────────────────────────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
     ┌────────────┐  ┌────────────┐  ┌────────────┐
     │  Supabase  │  │ Local PG   │  │  Directus  │
     │  Provider  │  │  Provider  │  │  Provider  │
     └────────────┘  └────────────┘  └────────────┘
           │              │                 │
           ▼              ▼                 ▼
      Supabase      PostgreSQL          Directus
      Auth API       Database            Users Table

The system determines which provider to use at runtime by reading the auth_provider_config table:

SELECT active_provider FROM auth_provider_config LIMIT 1;
-- Returns: 'supabase' | 'local' | 'directus'

This means you can switch providers without redeploying by updating a single database row.

1. User submits login form → POST /api/v1/auth/signin
2. API Gateway calls AuthService.signIn(email, password)
3. AuthService reads auth_provider_config.active_provider
4. Provider router delegates to appropriate provider:
   • Supabase: Calls Supabase Auth API
   • Local: Queries local_auth_credentials, verifies Argon2id hash
5. Provider returns AuthSession (user + tokens)
6. API Gateway returns session to frontend
7. Frontend stores access token, uses for authenticated requests

Stores password hashes and authentication metadata.

Indexes:

• idx_local_auth_user on user_id
• idx_local_auth_reset_token on reset_token
• idx_local_auth_verification_token on email_verification_token
• idx_local_auth_locked on locked_until

Tracks active sessions with refresh token management.

Revocation Reasons:

• logout - User logged out
• password_change - Password changed
• admin - Admin revoked session
• token_rotation - Refresh token rotated
• suspicious - Suspicious activity detected

Indexes:

• idx_sessions_user on (user_id, is_active)
• idx_sessions_token on token_hash
• idx_sessions_expires on expires_at
• idx_sessions_family on token_family

Social login connections for OAuth providers.

Unique Constraint: (provider, provider_user_id)

Global authentication configuration (singleton table).

Note: OAuth client secrets should be stored in environment variables, not the database.

SELECT * FROM auth_provider_config;

-- Switch to Local PostgreSQL
UPDATE auth_provider_config
SET active_provider = 'local', local_enabled = true, supabase_enabled = false;

-- Switch to Supabase
UPDATE auth_provider_config
SET active_provider = 'supabase', supabase_enabled = true, local_enabled = false;

-- Enable both (user chooses during signup)
UPDATE auth_provider_config
SET supabase_enabled = true, local_enabled = true, active_provider = 'supabase';

UPDATE auth_provider_config
SET
  local_password_min_length = 12,
  local_password_require_uppercase = true,
  local_password_require_lowercase = true,
  local_password_require_number = true,
  local_password_require_special = true;

-- Increase session lifetime to 30 days
UPDATE auth_provider_config
SET
  local_session_duration_hours = 720,
  jwt_refresh_token_expires_days = 30;

-- Shorter sessions for high-security environments
UPDATE auth_provider_config
SET
  local_session_duration_hours = 24,
  jwt_refresh_token_expires_days = 1,
  jwt_access_token_expires_minutes = 15;

-- Stricter lockout policy
UPDATE auth_provider_config
SET
  local_max_failed_login_attempts = 3,
  local_lockout_duration_minutes = 60;

-- More lenient policy
UPDATE auth_provider_config
SET
  local_max_failed_login_attempts = 10,
  local_lockout_duration_minutes = 15;

OAuth is supported when using the Supabase auth provider (active_provider = 'supabase').

High-level steps:

1. Create an OAuth app in Google/GitHub/Discord/etc.
2. Set the OAuth app callback/redirect URL to your Supabase callback:
   • https://<YOUR_SUPABASE_PROJECT_REF>.supabase.co/auth/v1/callback
3. In Supabase: Authentication → Providers
   • Enable the provider and paste the client ID/secret
4. In Supabase: Authentication → URL Configuration
   • Set Site URL and Redirect URLs (include your production domain + http://localhost:3050/**)

Guides:

• Supabase social login docs: https://supabase.com/docs/guides/auth/social-login
• SynthStack guide: OAuth Setup (Supabase)

OAuth is supported for both Supabase and Local auth providers via the service layer.

Never use a weak secret. Generate a cryptographically secure 256-bit key:

# macOS/Linux
openssl rand -base64 32

# Alternative
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

SynthStack implements refresh token rotation to detect token theft:

1. Each refresh token belongs to a token family (UUID)
2. When refreshing, the old token is invalidated and a new one is issued
3. If an old (already-rotated) token is reused, all tokens in that family are revoked
4. This detects token theft and prevents attackers from maintaining access

Recommendations by environment:

• Max failed attempts: 3-10 (5 recommended)
• Lockout duration: 15-60 minutes (30 recommended)
• Consider: Exponential backoff for repeated lockouts

Always enable in production:

UPDATE auth_provider_config SET local_require_email_verification = true;

Prevents:

• Fake account creation
• Email enumeration (with careful error messages)
• Spam/abuse

Never send JWT tokens over HTTP. Always use HTTPS in production:

# Force HTTPS redirect
server {
    listen 80;
    server_name api.synthstack.app;
    return 301 https://$host$request_uri;
}

Local auth uses Argon2id with:

• Memory cost: 65536 KB (64 MB)
• Iterations: 3
• Parallelism: 4 threads

This configuration resists GPU/ASIC attacks. Do not reduce these values.

All authentication endpoints are prefixed with /api/v1/auth.

Register a new user account.

Request:

curl -X POST https://api.synthstack.app/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123",
    "displayName": "John Doe"
  }'

Response (201):

{
  "session": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "a1b2c3d4e5f6...",
    "expiresAt": "2025-01-07T10:00:00Z",
    "provider": "local"
  },
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "displayName": "John Doe",
    "emailVerified": false,
    "createdAt": "2025-01-06T09:00:00Z"
  }
}

Sign in with email and password.

Request:

curl -X POST https://api.synthstack.app/api/v1/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123"
  }'

Response (200): Same as signup

Error (401):

{
  "error": "Invalid credentials",
  "code": "AUTH_INVALID_CREDENTIALS"
}

Error (423 - Account Locked):

{
  "error": "Account locked due to too many failed login attempts",
  "code": "AUTH_ACCOUNT_LOCKED",
  "lockedUntil": "2025-01-06T10:30:00Z"
}

Sign out and revoke the current session.

Request:

curl -X POST https://api.synthstack.app/api/v1/auth/signout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200):

{
  "message": "Signed out successfully"
}

Refresh access token using refresh token.

Request:

curl -X POST https://api.synthstack.app/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "a1b2c3d4e5f6..."
  }'

Response (200):

{
  "session": {
    "accessToken": "eyJhbGci...",
    "refreshToken": "x9y8z7w6...",
    "expiresAt": "2025-01-07T11:00:00Z"
  }
}

Note: Old refresh token is invalidated (token rotation).

Request password reset email.

Request:

curl -X POST https://api.synthstack.app/api/v1/auth/reset-password-request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Response (200):

{
  "message": "If an account exists with this email, a reset link has been sent"
}

Note: Always returns success to prevent email enumeration.

Complete password reset with token.

Request:

curl -X POST https://api.synthstack.app/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-email",
    "newPassword": "NewSecurePass456"
  }'

Response (200):

{
  "message": "Password reset successful"
}

Get authentication provider configuration.

Request:

curl https://api.synthstack.app/api/v1/auth/providers

Response (200):

{
  "activeProvider": "local",
  "availableProviders": ["local", "supabase"],
  "oauthProviders": {
    "google": { "enabled": true, "clientId": "123...apps.googleusercontent.com" },
    "github": { "enabled": true, "clientId": "Ov23li..." },
    "discord": { "enabled": false },
    "microsoft": { "enabled": false }
  },
  "features": {
    "emailVerificationRequired": true,
    "mfaSupported": false
  }
}

Get OAuth authorization URL.

Request:

curl "https://api.synthstack.app/api/v1/auth/oauth/google?redirect_uri=https://synthstack.app/auth/callback"

Response (200):

{
  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...",
  "state": "random-state-token"
}

Frontend redirects user to authUrl.

Handle OAuth callback (called by OAuth provider redirect).

Request:

curl -X POST https://api.synthstack.app/api/v1/auth/oauth/callback \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "code": "4/0AY0e...",
    "state": "random-state-token"
  }'

Response (200):

{
  "session": { "accessToken": "...", "refreshToken": "..." },
  "user": { "id": "...", "email": "[email protected]", ... }
}

Get current authenticated user profile.

Request:

curl https://api.synthstack.app/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGci..."

Response (200):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "displayName": "John Doe",
  "avatarUrl": "https://...",
  "emailVerified": true,
  "authProvider": "local",
  "createdAt": "2025-01-06T09:00:00Z"
}

✅ Fast setup needed - Get auth working in 5 minutes ✅ Managed service preference - Don't want to manage auth infrastructure ✅ Built-in OAuth - Need social login without manual setup ✅ Admin UI - Want dashboard for user management ✅ Small-medium scale - Under 50k users (free tier) ✅ Email templates - Need pre-built auth emails

✅ Self-hosted requirement - Must run on your infrastructure ✅ No external dependencies - Can't rely on third-party services ✅ Full data control - Data sovereignty requirements ✅ Cost optimization - High user count (>50k users) ✅ Email/password is enough - OAuth for local auth is coming later ✅ No vendor lock-in - Want to own the entire stack

1. Export Users from Supabase

-- Run in Supabase SQL editor
SELECT
  id, email, created_at, email_confirmed_at
FROM auth.users;

Export to CSV.

2. Switch Auth Provider

-- In your SynthStack database
UPDATE auth_provider_config
SET active_provider = 'local', local_enabled = true, supabase_enabled = false;

3. Import Users

-- Create users in app_users table
INSERT INTO app_users (id, email, auth_provider, email_verified, email_verified_at, date_created)
VALUES ('uuid-from-supabase', '[email protected]', 'local', true, '2025-01-01', '2025-01-01');

-- Users must reset passwords (no way to export Supabase password hashes)

4. Send Password Reset Emails

Notify all users to reset their passwords via the forgot password flow.

1. Export Users

SELECT u.id, u.email, u.date_created, u.email_verified
FROM app_users u
WHERE u.auth_provider = 'local';

2. Create Users in Supabase

Use Supabase Admin API:

const { createClient } = require('@supabase/supabase-js');
const supabase = createClient(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY);

for (const user of users) {
  await supabase.auth.admin.createUser({
    email: user.email,
    email_confirm: user.email_verified
  });
}

3. Switch Provider

UPDATE auth_provider_config
SET active_provider = 'supabase', supabase_enabled = true, local_enabled = false;

4. Update User Records

UPDATE app_users
SET auth_provider = 'supabase'
WHERE auth_provider = 'local';

Symptoms: 401 Unauthorized errors, "Invalid token" messages

Causes:

• JWT_SECRET mismatch between services
• Token expired
• Token format invalid

Solutions:

# 1. Verify JWT_SECRET is identical in all services
grep JWT_SECRET packages/*/\.env

# 2. Check token expiration
# Decode token at https://jwt.io
# Verify 'exp' claim is in the future

# 3. Verify token structure
# Should have format: Authorization: Bearer <token>

Symptoms: 423 Account Locked error

Cause: Too many failed login attempts

Solutions:

-- Check lockout status
SELECT email, failed_login_attempts, locked_until
FROM local_auth_credentials
WHERE email = '[email protected]';

-- Manually unlock account
UPDATE local_auth_credentials
SET
  failed_login_attempts = 0,
  locked_until = NULL
WHERE email = '[email protected]';

Prevention:

-- Increase lockout threshold
UPDATE auth_provider_config
SET local_max_failed_login_attempts = 10;

Symptoms: Redirect to error page, "redirect_uri_mismatch" error

Causes:

• Callback URL not registered with OAuth provider
• CORS issues
• HTTP instead of HTTPS in production

Solutions:

1. Verify callback URL in provider settings:

Google: https://console.cloud.google.com → Credentials
GitHub: https://github.com/settings/developers

Expected URL: https://api.synthstack.app/api/v1/auth/oauth/callback

2. Check CORS configuration (packages/api-gateway/src/index.ts):

app.register(cors, {
  origin: ['https://synthstack.app', 'http://localhost:5173'],
  credentials: true
});

3. Force HTTPS in production:

# Nginx config
add_header Strict-Transport-Security "max-age=31536000" always;

Symptoms: "Invalid or expired reset token" error

Cause: Token expired (1 hour lifetime) or already used

Solutions:

-- Check token expiration
SELECT
  email,
  reset_token,
  reset_token_expires_at,
  reset_token_expires_at > NOW() as is_valid
FROM local_auth_credentials
WHERE reset_token = 'token-from-email';

-- Generate new token (users should request reset again)
-- Tokens are one-time use and auto-expire after 1 hour

Symptoms: "Email not verified" errors, verification emails not sending

Causes:

• Email service not configured
• Verification disabled
• Token expired (24 hours)

Solutions:

1. Check email service configuration:

# Check Resend API key in root .env
grep RESEND_API_KEY .env

2. Verify email verification is enabled:

SELECT local_require_email_verification
FROM auth_provider_config;

-- Should be TRUE in production
UPDATE auth_provider_config
SET local_require_email_verification = true;

3. Manually verify a user:

UPDATE local_auth_credentials
SET
  email_verified = true,
  email_verified_at = NOW()
WHERE user_id = 'user-uuid';

UPDATE app_users
SET
  email_verified = true,
  email_verified_at = NOW()
WHERE id = 'user-uuid';

Symptoms: Users logged out after short time

Cause: Short session duration settings

Solutions:

-- Check current settings
SELECT
  jwt_access_token_expires_minutes,
  jwt_refresh_token_expires_days
FROM auth_provider_config;

-- Increase session duration
UPDATE auth_provider_config
SET
  jwt_access_token_expires_minutes = 120,  -- 2 hours
  jwt_refresh_token_expires_days = 30;     -- 30 days

Run this function periodically (via cron job) to purge old sessions:

SELECT cleanup_expired_sessions();
-- Returns: number of deleted sessions

Deletes:

• Sessions expired >7 days ago
• Revoked sessions >30 days old

Force logout a user (e.g., after password change or security incident):

SELECT revoke_all_user_sessions('user-uuid', 'password_change');
-- Returns: number of revoked sessions

Revocation reasons:

• logout - User logged out
• password_change - Password changed
• admin - Admin action
• suspicious - Security event

• Self-Hosting Guide - Deployment and configuration
• Feature Flags - Auth-related feature flags
• API Gateway README - API reference
• Email Service - Email configuration for auth emails

For issues, questions, or feature requests:

• GitHub Issues: https://github.com/your-repo/synthstack/issues
• Documentation: https://synthstack.app/docs
• Community Discord: https://discord.gg/synthstack