Skip to content

Environment Variable Reference

This page summarizes the important environment variables currently visible in the Seamless Auth auth server, server adapter, local starters, and CLI-generated stack.

The values here are meant to explain ownership boundaries. For exact defaults, always check the source repo .env.example or generated project files.


These values belong to seamless-auth-api.

Variable Purpose
NODE_ENV Runtime environment
HOST Bind host for the auth server
PORT Bind port for the auth server
APP_NAME Human-readable application name
APP_ID Application identifier
APP_ORIGINS CORS origins allowed to call the auth server
ISSUER Token issuer value

APP_ORIGINS and WebAuthn ORIGINS are related but not identical. APP_ORIGINS controls CORS for the auth API; ORIGINS controls WebAuthn browser origins in system config.


These values seed the system_config table when a row is missing, and are re-applied on every boot to rows that were never changed through the admin API. See How System Config Is Loaded.

Variable Purpose
DEFAULT_ROLES Roles assigned to newly created users
AVAILABLE_ROLES Roles allowed in the system
LOGIN_METHODS Enabled login methods: passkey, magic_link, email_otp, phone_otp, oauth
PASSKEY_LOGIN_FALLBACK_ENABLED Whether fallback methods can appear alongside passkey login
PROMPT_PASSKEY_ENROLLMENT true asks users with no passkey to enroll one after a code or magic-link sign-in; default false
PHISHING_RESISTANT_ONLY true accepts only passkeys to start a session; default false
OAUTH_PROVIDERS JSON array of OAuth provider configs
LOCKOUT_POLICY JSON login lockout policy
AUTHENTICATOR_POLICY JSON passkey authenticator policy, such as {"syncedPasskeys":"allow"}
RECOVERY_CODES JSON recovery code policy, default {"enabled":true,"requireAtEnrollment":false} (v0.20)
ACCOUNT_RECOVERY JSON self-service account recovery, default {"enabled":false,"delay":"24h"}; delay is 1h to 30d (v0.20)
ACCESS_TOKEN_TTL Access token lifetime, such as 30m
REFRESH_TOKEN_TTL Refresh token lifetime, such as 1h
SESSION_IDLE_TTL Session idle timeout, such as 8h (the default)
MAX_CONCURRENT_SESSIONS Sessions per user; null, none, or unlimited means no cap (the default); empty counts as unset
RATE_LIMIT Base request rate limit
DELAY_AFTER Slowdown threshold
FLOW_RATE_LIMITS JSON per-IP and per-identity limits for OTP, magic-link, and OAuth flows
RPID WebAuthn relying party ID
ORIGINS Comma-separated WebAuthn browser origins
APP_NAME Application name shown in auth experiences
FRONTEND_URL Frontend base URL for sign-in and magic-link links (optional)
MAGIC_LINK_REDIRECT_URIS Comma-separated exact-match magic-link destinations, such as myapp://auth (optional)

See System Config Reference for each key’s type, default, and parsing rule, and for the JSON shapes of AUTHENTICATOR_POLICY and FLOW_RATE_LIMITS.

OAUTH_PROVIDERS stores provider metadata, not provider client secrets. Each provider references a secret env var through clientSecretEnv.


The auth API can use a single DATABASE_URL or individual Postgres fields.

Variable Purpose
DATABASE_URL Full Postgres connection URL
DB_HOST Database host
DB_PORT Database port
DB_NAME Database name
DB_USER Database user
DB_PASSWORD Database password
DB_LOGGING Enables SQL logging from app and migrations

Prefer DATABASE_URL in containers and hosted environments if your infrastructure already provides one.


Variable Required Purpose
SEAMLESS_SERVICE_TOKEN Yes Shared service token for trusted server-to-auth calls
API_SERVICE_TOKEN No Older name for SEAMLESS_SERVICE_TOKEN, used only when it is unset
REFRESH_TOKEN_LOOKUP_SECRET Production HMAC key for indexed refresh-token lookup fingerprints
DECOY_SUBJECT_SECRET Production HMAC key for the decoy subjects POST /login returns for unknown identifiers
TOTP_SECRET_ENCRYPTION_KEY Production, once TOTP is used Encryption key for TOTP secrets at rest
OAUTH_STATE_SECRET Production, once OAuth is configured Signing secret for OAuth state
BREAK_GLASS_EMAILS No Comma-separated admin emails exempt from sign-in policy (v0.20)

From auth API v0.20 none of these falls back to the service token. With NODE_ENV=production the server refuses to start without REFRESH_TOKEN_LOOKUP_SECRET and DECOY_SUBJECT_SECRET, without TOTP_SECRET_ENCRYPTION_KEY while any TOTP credential exists, and without OAUTH_STATE_SECRET while an OAuth provider is configured, and it names each missing one. Adding an OAuth provider or starting TOTP enrollment answers 409 { "error": "secret_required", "variable": "..." } while its secret is unset. Development uses a fixed development-only value for each unset secret, with a warning.

Upgrading from a deployment that relied on the fallback (v0.19 and earlier): before upgrading, set each missing secret to the current SEAMLESS_SERVICE_TOKEN value, so existing sessions, TOTP enrollments and OAuth sign-ins in flight stay valid. Changing REFRESH_TOKEN_LOOKUP_SECRET later signs everyone out, and changing TOTP_SECRET_ENCRYPTION_KEY makes stored TOTP secrets unreadable. See v0.20 Release Notes.

BREAK_GLASS_EMAILS exempts a listed account only while it holds a role that satisfies admin:write. It still needs a passkey, TOTP or a recovery code, and every exempt sign-in emails every admin. It is kept out of system_config so no policy edit can remove it.


Variable Purpose
RPID Relying party ID used for passkeys
ORIGINS Allowed browser origins

These are especially important for local development. Mismatched hostnames or ports can break passkey flows even when the rest of the stack looks healthy.


Variable Purpose
LOGIN_METHODS Must include oauth to offer OAuth login
OAUTH_PROVIDERS JSON provider config array
OAUTH_STATE_SECRET OAuth state signing secret, required in production once a provider is configured
OAUTH_ALLOW_UNBOUND_STATE Removed in v0.20 and ignored, with a boot warning. Every OAuth callback must carry the binding from /start, as @seamless-auth/client 0.7.1 and later send it. In v0.19 true accepted a callback without one
OAUTH_PROVIDER_PRIVATE_HOSTS Comma-separated OAuth provider hosts allowed to resolve to private or loopback addresses in production, for an on-premises IdP. Link-local is always refused
Provider secret vars Values referenced by provider clientSecretEnv; names must end in _CLIENT_SECRET

Example provider configs reference secrets by name:

{
"id": "google",
"clientSecretEnv": "GOOGLE_CLIENT_SECRET"
}

GOOGLE_CLIENT_SECRET belongs in the deployed environment or secret manager, not in OAUTH_PROVIDERS or system_config.


The auth API can send OTPs and magic links directly when delivery is enabled.

Variable Purpose
MESSAGING_ENABLE_IN_DEV Enables direct delivery in development
MESSAGING_AWS_REGION AWS region for AWS-backed messaging
MESSAGING_EMAIL_FROM Sender address for email delivery
MESSAGING_SMS_PROVIDER SMS provider selection, such as aws or twilio
MESSAGING_SMS_FROM Sender number for SMS
MESSAGING_TWILIO_ACCOUNT_SID Twilio account SID
MESSAGING_TWILIO_AUTH_TOKEN Twilio auth token

When @seamless-auth/express owns delivery, the auth server can return external-delivery payloads to that trusted adapter instead of delivering messages itself.


Production access-token signing uses configured JWKS material.

Variable Purpose
SEAMLESS_JWKS_ACTIVE_KID Active signing key ID
SEAMLESS_JWKS_KEY_<kid>_PRIVATE Private key for the active key ID
SEAMLESS_JWKS_PUBLIC_KEYS Public JWKS key material

Keep retired public keys available until all tokens signed with them have expired.

Outside production the API generates its own signing key at startup instead:

Variable Default Purpose
SEAMLESS_DEV_KEYS_DIR ./keys/dev Directory for the dev key pair (/app/keys/dev in the image). Ignored in production.

The dev key ID is derived from the key’s JWK thumbprint (dev- plus 16 characters). See JWKS And Signing Keys.


The backend starters (Express, Fastify, and the full-stack Next.js template) read these values and pass them to their adapter (@seamless-auth/express, @seamless-auth/fastify, or @seamless-auth/nextjs).

Variable Purpose
AUTH_SERVER_URL Base URL for the private Seamless Auth API
AUTH_SERVER_ISSUER Optional. The issuer the auth server signs with, when it differs from AUTH_SERVER_URL. Passed to the adapter as both authServerIssuer and audience; unset or blank, both stay AUTH_SERVER_URL
COOKIE_SIGNING_KEY Secret for signed application auth cookies
API_SERVICE_TOKEN Shared service token for API-to-auth communication
APP_ORIGIN Issuer/origin value for the application API
JWKS_KID kid header on the service tokens the adapter signs for the auth API
UI_ORIGINS Browser origins allowed by the Express starter CORS

The adapter is the browser-facing cookie boundary. Do not put browser cookie custody directly on the raw auth API.

AUTH_SERVER_ISSUER matters when a starter runs on the host (npm run dev) against the seamless init --local Docker stack. The auth server there signs as http://auth:5312, its compose service name, while the host-run app calls http://localhost:5312. Without AUTH_SERVER_ISSUER=http://auth:5312 every sign-in fails with Invalid signed response from Auth Server. seamless-cli 0.19.0 or later fills it from the {{authServerIssuer}} template placeholder: http://auth:5312 on a local stack, and the instance URL on a managed instance. The generated docker-compose.yml also sets it on the api or web container, where AUTH_SERVER_URL and the issuer are both http://auth:5312. See Server SDKs: Auth server issuer.


The React starter and admin dashboard need the URL for the backend API where the auth adapter is mounted.

Variable Used by Purpose
VITE_API_URL Vite frontend and admin Backend API base URL
/config.js Admin dashboard image Runtime config injection path

The admin dashboard reads runtime config first, then falls back to Vite env values for local development.


In the generated local stack, these values often line up like this:

Service Common local URL
Auth API http://localhost:5312
Backend API http://localhost:3000
Web app http://localhost:5173
Admin dashboard http://localhost:5174

Inside Docker, service-to-service URLs use service names. For example, the API should call the auth server at http://auth:5312, not http://localhost:5312.


When documenting environment variables:

  • prefer .env.example, source config maps, or generated project files over older prose
  • label whether a variable belongs to the auth server, backend adapter, frontend, admin app, or CLI
  • keep raw secrets out of system config examples
  • distinguish required production secrets from development fallbacks