Reference
Environment variables
Complete reference for all environment variables read by Auth Service.
Environment variables
All variables are validated at startup using Zod. If a required variable is missing or invalid, the process exits with an error listing every failing field.
Server
| Variable | Required | Default | Description |
|---|---|---|---|
PORT | no | 3001 | TCP port the Fastify server binds to |
HOST | no | 0.0.0.0 | Bind address |
NODE_ENV | no | development | development, production, or test. Controls log level and transport. |
BetterAuth (required)
| Variable | Required | Default | Description |
|---|---|---|---|
BETTER_AUTH_SECRET | yes | — | Random secret used to sign sessions (min 16 chars). Generate with openssl rand -base64 32. |
BETTER_AUTH_URL | yes | — | Public base URL of Auth Service, e.g. https://auth.example.com. Used as the OIDC issuer and in email links. |
Database (required)
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL | yes | — | PostgreSQL connection string, e.g. postgres://user:pass@host:5432/dbname |
POSTGRES_USER | yes (Compose) | — | Postgres user — used by the postgres service in Compose |
POSTGRES_PASSWORD | yes (Compose) | — | Postgres password |
POSTGRES_DB | yes (Compose) | — | Database name |
POSTGRES_PORT | no | 5433 | Host-side port for the Postgres container (dev only) |
Bootstrap
| Variable | Required | Default | Description |
|---|---|---|---|
ADMIN_EMAIL | no | — | Email address for the superadmin created at first boot |
ADMIN_PASSWORD | no | — | Password for the superadmin (min 8 chars). If either variable is absent, bootstrap is skipped. |
CORS and sessions
| Variable | Required | Default | Description |
|---|---|---|---|
CORS_ORIGINS | no | http://localhost:5173 | Comma-separated list of allowed CORS origins |
SESSION_DOMAIN | no | — | When set, enables cross-subdomain cookies. Set to the apex domain, e.g. example.com. |
Email (SMTP)
All SMTP variables are optional. When SMTP_HOST is not set, password reset and verification emails are silently skipped.
| Variable | Required | Default | Description |
|---|---|---|---|
SMTP_HOST | no | — | SMTP server hostname |
SMTP_PORT | no | 587 | SMTP port. Port 465 enables implicit TLS; all others use STARTTLS. |
SMTP_USER | no | — | SMTP authentication username |
SMTP_PASS | no | — | SMTP authentication password |
SMTP_FROM | no | auth-service <no-reply@localhost> | From address for outgoing emails |
Templates
| Variable | Required | Default | Description |
|---|---|---|---|
TEMPLATES_DIR | no | — | Absolute path to a directory containing custom HTML templates for /login, /register, and /verify-email. See Custom templates. |
Stripe billing
| Variable | Required | Default | Description |
|---|---|---|---|
STRIPE_SECRET_KEY | no | — | Stripe secret API key (sk_live_… or sk_test_…). When absent, Stripe features are disabled. |
STRIPE_WEBHOOK_SECRET | no | — | Stripe webhook signing secret (whsec_…). Required for the webhook endpoint to validate Stripe events. |
Social login providers
Each provider requires both CLIENT_ID and CLIENT_SECRET to be set. If either is missing, the provider is disabled.
| Variable | Required | Default | Description |
|---|---|---|---|
GOOGLE_CLIENT_ID | no | — | Google OAuth app client ID |
GOOGLE_CLIENT_SECRET | no | — | Google OAuth app client secret |
GITHUB_CLIENT_ID | no | — | GitHub OAuth app client ID |
GITHUB_CLIENT_SECRET | no | — | GitHub OAuth app client secret |
LINKEDIN_CLIENT_ID | no | — | LinkedIn OAuth app client ID |
LINKEDIN_CLIENT_SECRET | no | — | LinkedIn OAuth app client secret |
MICROSOFT_CLIENT_ID | no | — | Microsoft OAuth app client ID |
MICROSOFT_CLIENT_SECRET | no | — | Microsoft OAuth app client secret |
APPLE_CLIENT_ID | no | — | Apple OAuth app client ID |
APPLE_CLIENT_SECRET | no | — | Apple OAuth app client secret |
Config keys for social providers are validated at startup, but the BetterAuth
socialProvider()plugins are only enabled forgithub. The remaining provider keys are reserved for future use.