Configuration
Auth Service is configured with environment variables only. They are validated by Zod when the process starts: a missing or malformed value stops the startup with a message listing every failing field.
This page covers the decisions you take for a new deployment. Every variable, with its default, is listed in the environment variables reference.
The three required values
| Variable | Description |
|---|---|
BETTER_AUTH_SECRET | Random secret (16 characters minimum). Generate it with openssl rand -base64 32 |
BETTER_AUTH_URL | Public base URL of the service, for example https://auth.example.com. It is the OIDC issuer and the base of every link sent by e-mail |
DATABASE_URL | PostgreSQL connection URL. The Compose file builds it from POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DB |
BETTER_AUTH_URL must be the URL your users and client applications reach, written as the root URL without a trailing slash. Tokens carry it verbatim as iss, and resource servers compare it with the issuer they trust.First administrator
Set ADMIN_EMAIL and ADMIN_PASSWORD before the first start. A superadmin is created when none exists; once one exists, later starts do not create another. The password needs at least 12 characters, and in production the placeholder from .env.example and other known default passwords are refused (no superadmin is created).
Browsers, cookies and proxies
| Variable | Use it when |
|---|---|
CORS_ORIGINS | A browser application calls the API from another origin. Origins of registered applications are added at runtime, see Protected resources and CORS |
SESSION_DOMAIN | Applications on sibling sub-domains must share the session cookie (example.com for auth.example.com and app.example.com) |
TRUST_PROXY_HOPS | The service sits behind a reverse proxy. Set it to the number of proxies (usually 1), otherwise rate limits see the proxy address instead of the client address. The default 0 ignores X-Forwarded-For |
When the process runs with NODE_ENV=production, e-mail verification is required by default, so SMTP_HOST must be set before the service starts. Either configure SMTP (see Email setup) or opt out explicitly with REQUIRE_EMAIL_VERIFICATION=false. The bundled Compose file forces NODE_ENV=production but passes REQUIRE_EMAIL_VERIFICATION=false unless .env sets it, so that stack starts without SMTP; set REQUIRE_EMAIL_VERIFICATION=true and SMTP_HOST for a deployment that verifies addresses.
Optional integrations
| Feature | Variables | Guide |
|---|---|---|
| Social login | GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET | Environment variables |
| Stripe billing and wallet top-ups | STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET | Stripe integration |
| LLM gateway | LITELLM_URL, WALLET_USD_TO_EUR_RATE, WALLET_MARGIN_PERCENT | LiteLLM gateway |
| Shared rate limits and admin events across instances | REDIS_URL | Deployment |
| Custom login pages and e-mails | TEMPLATES_DIR | Custom templates |
| Branding | APP_NAME, APP_LOGO_URL, APP_LOGO_DARK_URL, SHOWCASE | Environment variables |
| Replacing Okta, Auth0 or Keycloak | COMPAT_PROFILE and its overrides | Compatibility profiles |