.env.example

# Runtime environment
# Default: dev
# Allowed: dev | prod
APP_ENV=dev

# Log level
# Default:
#   dev  -> debug
#   prod -> info
# LOG_LEVEL=debug

# Enable Prometheus metric collection and GET /metrics.
# Default: false
# AUTHARA_METRICS_ENABLED=false

POSTGRESQL_HOST=postgres
POSTGRESQL_PORT=5432
POSTGRESQL_DATABASE=authara
POSTGRESQL_USERNAME=authara
POSTGRESQL_PASSWORD=authara

# PostgreSQL TLS mode shared by Core and the migrations image.
# Allowed: disable | require | verify-ca | verify-full
# Default: disable
POSTGRESQL_SSL_MODE=disable

# Optional path to a PEM-encoded PostgreSQL CA certificate.
# Mount the file at the same path in Core and the migrations container.
# POSTGRESQL_SSL_ROOT_CERT=/certs/postgresql-ca.pem

# Database timezone
# Default: UTC
POSTGRESQL_TIMEZONE=UTC

# Log SQL statements
# Default: false (true recommended in dev only)
POSTGRESQL_LOG_SQL=false

# Externally visible base URL of the application
# MUST NOT include /auth
# Examples:
#   http://localhost:3001  # docker-compose.dev.yaml development gateway
#   https://example.com
PUBLIC_URL=http://localhost:3001

# Optional parent domain shared by the access, refresh, and CSRF cookies.
# Leave empty for host-only cookies (recommended). The value must match the
# PUBLIC_URL host or be its registrable parent domain. Example for
# https://auth.example.com: example.com
# AUTHARA_COOKIE_DOMAIN=example.com

# Optional named Cloudflare Tunnel for the development gateway. Configure the
# tunnel route to http://gateway:3000, then enable its Compose profile.
# COMPOSE_PROFILES=tunnel
CLOUDFLARE_TUNNEL_TOKEN=

# Application name shown on hosted sign-in and account-creation pages.
# Default: Authara
# Leave unset to allow changes from the operator settings page.
# AUTHARA_APP_NAME=Authara

# Default redirect target after auth flows when return_to is not provided.
# Must be a safe relative path.
# Default: /
# AUTHARA_DEFAULT_RETURN_TO=/

# Trust X-Forwarded-For / X-Real-IP only from the listed proxy networks.
# If enabled without a valid CIDR, Authara warns and ignores forwarded headers.
# Default: false
AUTHARA_TRUST_PROXY_HEADERS=false
# Comma-separated IPv4/IPv6 CIDRs, for example: 10.20.0.0/16,fd00:20::/64
# AUTHARA_TRUSTED_PROXY_CIDRS=

# JWT issuer (iss claim)
AUTHARA_JWT_ISSUER=authara

# Active signing key ID
AUTHARA_JWT_ACTIVE_KEY_ID=key-2026-01

# Ed25519 private signing seeds. Core keeps these private and publishes only
# the derived public keys at /auth/.well-known/jwks.json.
# Format: keyID:base64Seed,keyID2:base64Seed2
# Generate each value with: openssl rand -base64 32
# This checked-in value is for local development only; replace it in production.
AUTHARA_JWT_PRIVATE_KEYS=key-2026-01:MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDE=

# HMAC keys used only to hash email verification codes. Keep these separate
# from JWT signing keys and retain old values until their codes have expired.
AUTHARA_CHALLENGE_VERIFICATION_CODE_ACTIVE_KEY_ID=challenge-2026-01
AUTHARA_CHALLENGE_VERIFICATION_CODE_KEYS=challenge-2026-01:YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUY=

# Access token lifetime
# Default: 10 minutes; maximum: 1440 minutes (24 hours)
# AUTHARA_ACCESS_TOKEN_TTL_MINUTES=10

# Absolute session lifetime
# Default: 60 days
# AUTHARA_SESSION_TTL_DAYS=60

# How often the cleanup leader removes expired and revoked session data
# Default: 5m
# AUTHARA_SESSION_CLEANUP_INTERVAL=5m

# Refresh token lifetime
# Default: 14 days
# AUTHARA_REFRESH_TOKEN_TTL_DAYS=14

# Refresh token rotation policy
#
# Controls how often refresh tokens are rotated.
#
# Supported values:
#
#   "" (unset) | "0" | "disabled" | "off"
#       - Rotation disabled
#       - Refresh token is reused until it expires
#
#   "always"
#       - Rotate refresh token on every use
#
#   <duration>
#       - Minimum interval between rotations
#       - Must be a valid Go duration string
#         (examples: 15m, 1h, 24h)
#
# Default: 24h
#
# AUTHARA_REFRESH_TOKEN_ROTATION_INTERVAL=24h
# Require fresh authentication before sensitive account and administrative
# mutations. When false, an active session has full mutation authority.
# Default: true
# AUTHARA_RECENT_AUTHENTICATION_ENABLED=true
# Maximum age of a proof accepted for sensitive mutations. Range: 1m to 1h.
# Default: 10m
# AUTHARA_RECENT_AUTHENTICATION_WINDOW=10m

# Allow password login with either an email address or username. When disabled,
# the hosted login form and password-login API accept email addresses only.
# Default: false
# AUTHARA_USERNAME_LOGIN_ENABLED=false

# Response to a newly detected passkey sign-counter anomaly.
# Allowed: alert | restrict | restrict_and_revoke
# Default: alert
# AUTHARA_PASSKEY_CLONE_RESPONSE=alert

# Send a generic security email for a newly detected anomaly. The message does
# not expose credential IDs, public keys, authenticator IDs, or counter values.
# Default: true
# AUTHARA_PASSKEY_CLONE_NOTIFY_USER=true

# Minimum Unicode-character length for newly created passwords. Existing
# passwords remain valid. Passphrases are encouraged; no composition rules are
# applied. Range: 8 to 128. A production value of 15 or more is recommended.
# Default: 8
# AUTHARA_PASSWORD_MIN_LENGTH=15

# Organization mode.
# Default: single
# Allowed: personal | single | multi
# Choose before first production use. Changing this after users/orgs exist
# is currently unsupported.
# personal: direct signup creates a hidden personal org; invitations disabled.
# single: direct signup creates one team org; invite signup joins that org.
# multi: direct signup creates a personal org; invite signup also joins invited org.
# AUTHARA_ORG_MODE=single

# Allow authenticated clients to manage non-capacity organization data through
# Authara's public API. Organization/invitation creation and invitation resend
# remain internal-only. Internal bearer access always remains enabled.
# Default: false
# AUTHARA_PUBLIC_ORGANIZATION_MANAGEMENT_ENABLED=false

# Organization invitation lifetime.
# Default: 168h (7 days)
# AUTHARA_ORGANIZATION_INVITATION_TTL=168h

# Bearer token for server-to-server calls to /auth/internal/v1.
# Generate with: openssl rand -base64 32
# AUTHARA_INTERNAL_API_TOKEN=replace-with-random-internal-token

# Comma-separated list of enabled OAuth providers
# Supported: google, apple, microsoft
# Default: empty (no OAuth providers enabled)
AUTHARA_OAUTH_PROVIDERS=

# Google OAuth web client credentials
# Required if AUTHARA_OAUTH_PROVIDERS has 'google'
# AUTHARA_OAUTH_GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
# AUTHARA_OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret

# Microsoft identity platform SPA configuration. Register
# https://your-domain/auth/oauth/microsoft/redirect as an SPA redirect URI,
# and optionally add verified_primary_email and xms_edov as ID-token claims.
# Required if AUTHARA_OAUTH_PROVIDERS has 'microsoft'. Tenant may be a tenant
# UUID, common, organizations, or consumers.
# AUTHARA_OAUTH_MICROSOFT_CLIENT_ID=00000000-0000-0000-0000-000000000000
# AUTHARA_OAUTH_MICROSOFT_TENANT_ID=common

# Sign in with Apple web configuration. All values are required when 'apple'
# is enabled. Encode the downloaded .p8 file as one line, for example:
# base64 < AuthKey_KEYID.p8 | tr -d '\n'
# Generate the refresh-token encryption key with: openssl rand -base64 32
# AUTHARA_OAUTH_APPLE_CLIENT_ID=com.example.web
# AUTHARA_OAUTH_APPLE_TEAM_ID=ABCDE12345
# AUTHARA_OAUTH_APPLE_KEY_ID=XYZ9876543
# AUTHARA_OAUTH_APPLE_PRIVATE_KEY_BASE64=base64-encoded-p8-file
# AUTHARA_OAUTH_APPLE_TOKEN_ACTIVE_KEY_ID=key-1
# AUTHARA_OAUTH_APPLE_TOKEN_KEYS=key-1:replace-with-base64-32-byte-secret

# ------------------------------------------------------------
# Rate limiting
# ------------------------------------------------------------
#
# These limits protect against brute-force login attempts
# and automated signup abuse.
#
# Limits are applied per:
#   - IP address
#   - Email address
#
# If a limit is exceeded, Authara returns HTTP 429.
#
# NOTE:
# - With AUTHARA_CACHE_PROVIDER=noop, limits are per-instance in memory.
# - With AUTHARA_CACHE_PROVIDER=redis, limits and access-token revocations are
#   shared through Redis.
# - Leave these variables unset to manage rate limits from the operator UI.
#

# Login rate limits:

# Max login attempts per IP within window
# Default: 5
# AUTHARA_RATE_LIMIT_LOGIN_IP_LIMIT=5

# Login IP window (Go duration)
# Default: 1m
# AUTHARA_RATE_LIMIT_LOGIN_IP_WINDOW=1m

# Max login attempts per email address or enabled username within window
# Default: 10
# AUTHARA_RATE_LIMIT_LOGIN_EMAIL_LIMIT=10

# Login email/enabled-username window (Go duration)
# Default: 1h
# AUTHARA_RATE_LIMIT_LOGIN_EMAIL_WINDOW=1h


# Signup rate limits:

# Max signup attempts per IP within window
# Default: 3
# AUTHARA_RATE_LIMIT_SIGNUP_IP_LIMIT=3

# Signup IP window (Go duration)
# Default: 1h
# AUTHARA_RATE_LIMIT_SIGNUP_IP_WINDOW=1h

# Max signup attempts per email within window
# Default: 3
# AUTHARA_RATE_LIMIT_SIGNUP_EMAIL_LIMIT=3

# Signup email window (Go duration)
# Default: 24h
# AUTHARA_RATE_LIMIT_SIGNUP_EMAIL_WINDOW=24h

# Password reset rate limits:

# Max password reset attempts per IP within window
# Default: 5
# AUTHARA_RATE_LIMIT_PASSWORD_RESET_IP_LIMIT=5

# Password reset IP window (Go duration)
# Default: 1h
# AUTHARA_RATE_LIMIT_PASSWORD_RESET_IP_WINDOW=1h

# Max password reset attempts per email within window
# Default: 3
# AUTHARA_RATE_LIMIT_PASSWORD_RESET_EMAIL_LIMIT=3

# Password reset email window (Go duration)
# Default: 24h
# AUTHARA_RATE_LIMIT_PASSWORD_RESET_EMAIL_WINDOW=24h

# Passkey login rate limits:

# Max passkey login option requests per IP within window
# Default: 30
# AUTHARA_RATE_LIMIT_PASSKEY_LOGIN_IP_LIMIT=30

# Passkey login IP window (Go duration)
# Default: 10m
# AUTHARA_RATE_LIMIT_PASSKEY_LOGIN_IP_WINDOW=10m

# Challenge verification rate limits:

# Max challenge verification attempts per IP within window
# Default: 30
# AUTHARA_RATE_LIMIT_CHALLENGE_VERIFY_IP_LIMIT=30

# Challenge verification IP window (Go duration)
# Default: 10m
# AUTHARA_RATE_LIMIT_CHALLENGE_VERIFY_IP_WINDOW=10m

# Challenge resend rate limits:

# Max challenge resend attempts per IP within window
# Default: 10
# AUTHARA_RATE_LIMIT_CHALLENGE_RESEND_IP_LIMIT=10

# Challenge resend IP window (Go duration)
# Default: 1h
# AUTHARA_RATE_LIMIT_CHALLENGE_RESEND_IP_WINDOW=1h

# ----------------------------
# In-memory limiter safety
# ----------------------------

# Cleanup sweep frequency (number of calls between sweeps)
# Default: 200
# AUTHARA_RATE_LIMIT_CLEANUP_EVERY=200

# Maximum number of stored rate limit keys
# Hard safety valve to prevent memory exhaustion
# Default: 50000
# AUTHARA_RATE_LIMIT_MAX_ENTRIES=50000

# ------------------------------------------------------------
# Webhooks
# ------------------------------------------------------------

# Webhook endpoint URL
# If empty, webhooks are disabled
# Example:
#   https://your-app.com/webhooks/authara
# AUTHARA_WEBHOOK_URL=https://your-app.com/webhooks/authara

# Shared secret used to sign webhook requests
# Must match the secret used by your application to verify signatures
# AUTHARA_WEBHOOK_SECRET=replace-with-at-least-32-random-characters

# Comma-separated list of enabled events
#
# Default: empty → all events enabled
#
# Example:
#   user.created,user.deleted,organization.invitation.created
#
# Supported events:
#   user.created
#   user.updated
#   user.deleted
#   organization.created
#   organization.updated
#   organization.deleted
#   organization.membership.created
#   organization.membership.updated
#   organization.membership.deleted
#   organization.invitation.created
#   organization.invitation.accepted
#   organization.invitation.revoked
#
# AUTHARA_WEBHOOK_ENABLED_EVENTS=

# HTTP timeout for webhook delivery
#
# Must be shorter than AUTHARA_WEBHOOK_PROCESSING_STALE_AFTER
#
# Default: 5s
# AUTHARA_WEBHOOK_TIMEOUT=5s

# Number of concurrent webhook delivery workers
# Default: 2
# AUTHARA_WEBHOOK_WORKER_COUNT=2

# Retry and maintenance defaults
# AUTHARA_WEBHOOK_MAX_DELIVERY_ATTEMPTS=3
# AUTHARA_WEBHOOK_PROCESSING_STALE_AFTER=2m
# AUTHARA_WEBHOOK_STALE_REAPER_INTERVAL=1m
# AUTHARA_WEBHOOK_DELIVERED_RETENTION=24h
# AUTHARA_WEBHOOK_FAILED_RETENTION=720h
# AUTHARA_WEBHOOK_CLEANUP_INTERVAL=1h
# AUTHARA_WEBHOOK_MAINTENANCE_BATCH_SIZE=1000

# ------------------------------------------------------------
# Database connection pool
# ------------------------------------------------------------
#
# Controls how many concurrent database connections Authara uses.
#
# IMPORTANT:
# - Must be tuned relative to Postgres max_connections
# - Applies per Authara instance
#
# Rule of thumb:
#   max_connections (Postgres) / number_of_instances ≈ MaxOpenConns
#
# Example:
#   Postgres max_connections = 200
#   1 instance → 40–80
#   2 instances → 20–40 each
#

# Maximum number of open connections to the database
#
# Default: 40
#
# Increase for higher throughput, but beware:
# - Too high → DB overload ("too many clients")
# - Too low → request queuing
#
AUTHARA_DB_MAX_OPEN_CONNS=40

# Maximum number of idle connections in the pool
#
# Default: 20
#
# Should be <= MAX_OPEN_CONNS
# Higher = better latency, more memory usage
#
AUTHARA_DB_MAX_IDLE_CONNS=20

# Maximum lifetime of a connection
#
# Ensures connections are periodically recycled
# (important for load balancers, proxies, etc.)
#
# Default: 30m
#
AUTHARA_DB_CONN_MAX_LIFETIME=30m

# Maximum idle time of a connection
#
# Idle connections beyond this time are closed
#
# Default: 5m
#
AUTHARA_DB_CONN_MAX_IDLE_TIME=5m

# ------------------------------------------------------------
# Cache
# ------------------------------------------------------------
#
# Supported:
#   noop  -> no shared cache
#   redis -> shared rate limits and immediate access-token revocation
#
# Default: noop
AUTHARA_CACHE_PROVIDER=noop

# Access-token revocation guarantee:
#   immediate -> Redis-backed revocation; protected requests fail closed if Redis is unavailable
#   expiry    -> no online revocation; issued tokens may remain valid until expiry (max 10m)
# Production with the noop provider must explicitly acknowledge expiry mode.
AUTHARA_ACCESS_TOKEN_REVOCATION_MODE=expiry

# Redis connection settings
# Used when AUTHARA_CACHE_PROVIDER=redis
#
# In docker-compose.dev.yaml, use host "redis".
# Outside Docker, localhost is usually correct.
#
AUTHARA_REDIS_HOST=redis
AUTHARA_REDIS_PORT=6379
# AUTHARA_REDIS_PASSWORD=
AUTHARA_REDIS_DB=0

# ------------------------------------------------------------
# Access Policy
# ------------------------------------------------------------
#
# When enabled, only emails explicitly allowed in the system
# may register and authenticate.
#
# If disabled, all emails are accepted.
#

# Enable email allowlist enforcement
# Default: false
# Leave unset to keep this setting editable in the operator UI.
# AUTHARA_ACCESS_POLICY_ALLOWLIST_ENABLED=false


# ------------------------------------------------------------
# Challenge / Verification
# ------------------------------------------------------------

# Enable optional email-verification challenges.
# Session-bound authentication challenges for sensitive mutations remain enabled.
# Default: false
AUTHARA_CHALLENGE_ENABLED=true

# Lifetime of a challenge (total window)
# Default: 30m
# Leave unset to keep this setting editable in the operator UI.
# AUTHARA_CHALLENGE_TTL=30m

# Lifetime of verification code
# MUST be <= CHALLENGE_TTL
# Default: 10m
# Leave unset to keep this setting editable in the operator UI.
# AUTHARA_CHALLENGE_VERIFICATION_CODE_TTL=10m

# Max wrong attempts before challenge is invalid
# Default: 5
# Leave unset to keep this setting editable in the operator UI.
# AUTHARA_CHALLENGE_MAX_ATTEMPTS=5

# Max resend attempts
# Default: 3
# Leave unset to keep this setting editable in the operator UI.
# AUTHARA_CHALLENGE_MAX_RESENDS=3

# Minimum time between resends
# Default: 30s
# Leave unset to keep this setting editable in the operator UI.
# AUTHARA_CHALLENGE_MIN_RESEND_INTERVAL=30s

# ------------------------------------------------------------
# Email
# ------------------------------------------------------------

# Email provider
# Supported:
#   noop  -> logs emails (dev)
#   smtp  -> real email sending
#
# Default: noop
# Production requires smtp because password recovery is always available.
AUTHARA_EMAIL_PROVIDER=noop

# Sender email address (required for smtp)
# AUTHARA_EMAIL_FROM=noreply@authara.local

# SMTP host (required for smtp)
# AUTHARA_EMAIL_SMTP_HOST=localhost

# SMTP port
# Default: 587
# AUTHARA_EMAIL_SMTP_PORT=587

# SMTP username (optional)
# AUTHARA_EMAIL_SMTP_USERNAME=

# SMTP password (optional)
# AUTHARA_EMAIL_SMTP_PASSWORD=

# Enforce STARTTLS
# Default: true
# AUTHARA_EMAIL_SMTP_TLS=true

# SMTP timeout
# Default: 10s
# AUTHARA_EMAIL_SMTP_TIMEOUT=10s

# ------------------------------------------------------------
# Email Worker
# ------------------------------------------------------------

# Number of concurrent workers
# Default: 2
AUTHARA_EMAIL_WORKER_COUNT=1

# Poll interval when no jobs available
# Default: 2s
AUTHARA_EMAIL_WORKER_POLL_INTERVAL=2s

# Max attempts per email job
# Default: 100
# Leave unset to keep this setting editable in the operator UI.
# AUTHARA_EMAIL_JOB_MAX_ATTEMPTS=100

# Age after which an in-progress email delivery is considered abandoned.
# Must be greater than AUTHARA_EMAIL_SMTP_TIMEOUT.
# Default: 2m
# AUTHARA_EMAIL_PROCESSING_STALE_AFTER=2m

# How often abandoned email deliveries are recovered
# Default: 1m
# AUTHARA_EMAIL_STALE_REAPER_INTERVAL=1m

# Maximum email jobs recovered in one maintenance batch
# Default: 1000
# AUTHARA_EMAIL_MAINTENANCE_BATCH_SIZE=1000

# ------------------------------------------------------------
# Email Cleanup
# ------------------------------------------------------------

# How often the cleanup leader applies email and challenge retention
# Default: 1h
# AUTHARA_EMAIL_CLEANUP_INTERVAL=1h

# Delete sent emails after duration
# Default: 30 days
# Leave unset to keep this setting editable in the operator UI.
# AUTHARA_EMAIL_CLEANUP_SENT_AFTER=720h

# Delete failed emails after duration
# Default: 90 days
# Leave unset to keep this setting editable in the operator UI.
# AUTHARA_EMAIL_CLEANUP_FAILED_AFTER=2160h

# ------------------------------------------------------------
# Audit and security-event cleanup
# ------------------------------------------------------------

# Delete operator audit events after this many days
# Default: 180
# AUTHARA_OPERATOR_AUDIT_RETENTION_DAYS=180

# How often the cleanup leader applies admin audit retention
# Default: 24h
# AUTHARA_ADMIN_AUDIT_CLEANUP_INTERVAL=24h

# How often the cleanup leader applies security-event retention
# Default: 24h
# AUTHARA_SECURITY_EVENT_CLEANUP_INTERVAL=24h