.env.example

# Auth API Environment Variables
# This file documents the environment variables used by the better-auth service.
# In Docker, these are set in docker-compose.yaml
# For local development without Docker, copy to .env.local

# ===========================
# Node Environment
# ===========================
NODE_ENV=development
PORT=3002
LOG_LEVEL=info

# ===========================
# Database Configuration
# ===========================
DATABASE_URL=postgresql://user:pass@localhost:5432/database?schema=auth
DATABASE_SCHEMA=auth
# Upper bound per auth-api replica. SAR-1385 production sets 10 so two replicas
# reserve at most 20 database connections.
POSTGRES_POOL_MAX=20

# ===========================
# Redis/ValKey Configuration
# ===========================
# Used for Better Auth secondary storage (session data and rate limiting)
#
# For local development (standalone mode):
REDIS_URL=redis://localhost:6379/1
#
# For production/staging (Sentinel mode - high availability):
# Set VALKEY_SENTINEL_HOST to enable Sentinel mode (REDIS_URL will be ignored)
VALKEY_SENTINEL_HOST=domain-staging-valkey
VALKEY_SENTINEL_PORT=26379
VALKEY_SENTINEL_MASTER_NAME=mymaster

# ===========================
# Better-Auth Configuration
# ===========================
# Subdomain Routing (auth is on its own subdomain)
# Local Development: http://localhost:3002
# Staging: https://auth-staging.domain.com
# Production: https://auth.domain.com
BETTER_AUTH_URL=http://localhost:3002
# SECURITY: Generate with: openssl rand -base64 32
# Must be at least 32 characters and cryptographically random
BETTER_AUTH_SECRET=GENERATE_NEW_SECRET_DO_NOT_USE_THIS_VALUE
BETTER_AUTH_TRUST_HOST=true

# JWT audience consumed by relying services. When blank, BETTER_AUTH_URL is used.
JWT_AUDIENCE=

# Dedicated least-privilege machine credential for POST /token/introspect.
# Provision this from a secret manager; never commit a real value.
TOKEN_INTROSPECTION_CLIENT_ID=token-introspection-client
TOKEN_INTROSPECTION_BEARER_TOKEN=
TOKEN_INTROSPECTION_RATE_LIMIT_MAX=120

# Workload identity is disabled unless explicitly enabled. These routes are
# server/workload-only and never accept browser sessions or human JWTs for minting.
WORKLOAD_IDENTITY_ENABLED=false
# Configure a consumer-specific audience separate from JWT_AUDIENCE.
WORKLOAD_JWT_AUDIENCE=
WORKLOAD_TOKEN_ENDPOINT_URL=http://localhost:3002/workload/token
WORKLOAD_RENEWAL_ENDPOINT_URL=http://localhost:3002/workload/token/renew
# Dedicated registrar/operator credential, generated and provisioned by a secret manager.
WORKLOAD_OPERATOR_BEARER_TOKEN=
WORKLOAD_TOKEN_TTL_SECONDS=300
WORKLOAD_GRANT_TTL_SECONDS=300
# Rotating credentials use a domain-separated key derived from BETTER_AUTH_SECRET.
WORKLOAD_RENEWAL_TTL_SECONDS=31536000
WORKLOAD_DPOP_CLOCK_SKEW_SECONDS=60
WORKLOAD_RATE_LIMIT_MAX=120

# ===========================
# Email Configuration (SendGrid)
# ===========================
SENDGRID_API_KEY=your-sendgrid-api-key-here
SENDGRID_FROM_EMAIL=noreply@example.com
SENDGRID_FROM_NAME=YourApp
# Optional: Use SendGrid Dynamic Templates (format: d-xxxxxxxxxxxxx)
SENDGRID_VERIFICATION_TEMPLATE_ID=
SENDGRID_RESET_TEMPLATE_ID=
SUPPORT_EMAIL=support@example.com

# Email Verification Settings
REQUIRE_EMAIL_VERIFICATION=false

# ===========================
# OAuth Providers (Optional)
# ===========================
# GitHub OAuth (get from https://github.com/settings/developers)
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

# Google OAuth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
# Optional public callback override for apps that proxy auth routes.
GOOGLE_REDIRECT_URI=

# ===========================
# Application Branding
# ===========================
APP_NAME=YourApp
COOKIE_PREFIX=yourapp
PRODUCTION_DOMAIN=example.com
STAGING_DOMAIN=staging.example.com

# ===========================
# Cookie Domain Configuration
# ===========================
# Set cookie domain for cross-subdomain sharing (WITHOUT leading dot per Better Auth spec)
# Development: Not used (hardcoded to "localhost")
# Staging: domain.com (shares cookies between auth-staging and staging subdomains)
# Production: domain.com (shares cookies between auth and www subdomains)
# Leave empty to disable cross-subdomain cookies (uses exact request domain)
COOKIE_DOMAIN=domain.com

# ===========================
# Session Configuration
# ===========================
SESSION_EXPIRES_IN=86400
SESSION_UPDATE_AGE=3600
SESSION_SECURE_COOKIES=false

# ===========================
# CORS Configuration
# ===========================
# Local Development: localhost origins
# Staging: https://staging.domain.com,https://api-staging.domain.com
# Production: https://domain.com,https://api.domain.com
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

# ===========================
# Security
# ===========================
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW=900000
# Trust proxy setting for Express (affects X-Forwarded-* header handling)
# Default: 1 (trust first proxy - safe for typical k8s ingress)
# Values: 1, true (trust all), or specific IP/CIDR range
# TRUST_PROXY=1

# ===========================
# Cloudflare Turnstile (Spam Protection)
# ===========================
# Disabled in development mode (localhost not allowed in Cloudflare)
# Get secret key from: https://dash.cloudflare.com/
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
TURNSTILE_ENABLED=false
# Optional: Development bypass token (NEVER works in production)
# Set a random value to bypass Turnstile in non-production environments
# TURNSTILE_BYPASS_TOKEN=your-random-dev-bypass-token

# ===========================
# Frontend URL
# ===========================
# Local Development: http://localhost:5173
# Staging: https://staging.domain.com
# Production: https://domain.com
FRONTEND_URL=http://localhost:5173

# ===========================
# Core API URL (for internal communication)
# ===========================
# Local Development: http://localhost:3001
# Staging: https://api-staging.domain.com
# Production: https://api.domain.com
API_URL=http://localhost:3001

# ===========================
# Webhooks (Optional)
# ===========================
# Optional: Call this webhook after email verification or social signup
# Webhook receives: { event: "user.email_verified"|"user.social_signup", user: {...}, timestamp: "..." }
# Leave empty to disable welcome email webhooks
# Local Development: http://localhost:3001/internal/webhooks/auth-events
# Staging: https://api-staging.domain.com/internal/webhooks/auth-events
# Production: https://api.domain.com/internal/webhooks/auth-events
WELCOME_EMAIL_WEBHOOK_URL=
AUTH_WEBHOOK_SECRET=