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.
Auth API Server Runtime
Section titled “Auth API Server Runtime”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.
System Config Bootstrap
Section titled “System Config Bootstrap”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.
Database
Section titled “Database”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.
Service And Security Secrets
Section titled “Service And Security Secrets”| 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.
WebAuthn
Section titled “WebAuthn”| 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.
Messaging
Section titled “Messaging”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.
JWKS And Signing Keys
Section titled “JWKS And Signing Keys”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.
Starter Environment
Section titled “Starter Environment”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.
Frontend And Admin Runtime
Section titled “Frontend And Admin Runtime”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.
Common Local URLs
Section titled “Common Local URLs”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.
Docs Rule
Section titled “Docs Rule”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