Configuration

All ezAuth configuration is done through environment variables. Set them in a .env file or your deployment environment.

Database & Cache

Variable	Default	Description
`DATABASE_URL`	—	PostgreSQL async connection string (e.g., `postgresql+asyncpg://user:pass@host:5432/ezauth`)
`REDIS_URL`	`redis://localhost:6379/0`	Redis connection URL

Variable	Default	Description
`JWT_ALGORITHM`	`RS256`	JWT signing algorithm
`JWT_ACCESS_TOKEN_EXPIRE_MINUTES`	`15`	Access token lifetime in minutes
`JWT_REFRESH_TOKEN_EXPIRE_DAYS`	`30`	Refresh token lifetime in days
`SESSION_COOKIE_NAME`	`__session`	Name of the session cookie
`SESSION_COOKIE_DOMAIN`	`""`	Cookie domain (empty = inferred from request)
`SESSION_COOKIE_SECURE`	`true`	Require HTTPS for cookies

Variable	Default	Description
`SES_REGION`	`us-east-1`	AWS SES region
`SES_SENDER`	—	Default sender email address
`SES_SENDER_NAME`	`EZAuth`	Default sender display name

Per-application sender settings can be configured in the dashboard. The environment variables set the defaults for new applications.

Variable	Default	Description
`SIGNUP_RATE_LIMIT_IP`	`60:10`	Max signups per IP (window_seconds:max_count)
`SIGNUP_RATE_LIMIT_EMAIL`	`300:1`	Max signups per email (window_seconds:max_count)
`SIGNIN_RATE_LIMIT_IP`	`60:10`	Max sign-ins per IP

Variable	Default	Description
`HASHCASH_ENABLED`	`true`	Require proof-of-work for signups
`HASHCASH_DIFFICULTY`	`5`	Number of leading zero bits required
`HASHCASH_CHALLENGE_TTL`	`300`	Challenge expiry in seconds
`HASHCASH_TIME_COST`	`2`	Argon2 time parameter
`HASHCASH_MEMORY_COST`	`19456`	Argon2 memory parameter (KiB)

Variable	Default	Description
`VERIFICATION_TOKEN_EXPIRE_MINUTES`	`60`	Email verification link/code TTL
`MAGIC_LINK_EXPIRE_MINUTES`	`15`	Magic link TTL

Variable	Default	Description
`CONFIRMATIONS_API_URL`	`https://api.confirmations.info`	Bot challenge verification API
`BOT_AUTH_TIMESTAMP_TOLERANCE`	`300`	Max age of bot auth signature (seconds)

Variable	Default	Description
`OAUTH_STATE_TTL_SECONDS`	`600`	OAuth CSRF state TTL

Variable	Default	Description
`S3_ENDPOINT_URL`	`""`	S3-compatible endpoint URL
`S3_ACCESS_KEY_ID`	`""`	S3 access key
`S3_SECRET_ACCESS_KEY`	`""`	S3 secret key
`S3_BUCKET_NAME`	`""`	S3 bucket name
`S3_REGION`	`us-east-1`	S3 region
`OBJECT_STORAGE_MAX_OBJECT_BYTES`	`52428800`	Max single object size (50 MB)
`OBJECT_STORAGE_LIMIT_BYTES`	`1073741824`	Total storage per app (1 GB)

Variable	Default	Description
`CUSTOM_TABLES_STORAGE_LIMIT_BYTES`	`104857600`	Max table storage per app (100 MB)

The dashboard has no shared password. Sign-in emails a single-use code to an address listed below, or to an application’s owner_email.

Variable	Default	Description
`DASHBOARD_ADMIN_EMAILS`	`""`	Comma-separated addresses granted superadmin access
`DASHBOARD_SESSION_TTL_SECONDS`	`43200`	Dashboard session lifetime (12 hours)
`DASHBOARD_ALLOWED_ORIGINS`	`""`	Comma-separated origins allowed to call the dashboard cross-origin
`INTERNAL_API_SECRET`	`""`	Shared secret for internal endpoints reached through the proxy

Variable	Default	Description
`ENVIRONMENT`	`development`	Set to `production` to reject development defaults at startup
`PUBLIC_BASE_URL`	`http://localhost:8000`	Public origin, used for email links and OAuth redirect URIs
`DB_POOL_SIZE`	`10`	Connection pool size
`DB_MAX_OVERFLOW`	`20`	Connections allowed beyond the pool size
`DB_POOL_RECYCLE_SECONDS`	`1800`	Recycle connections older than this

Variable	Default	Description
`SESSION_REVOCATION_CHECK`	`true`	Confirm the session row on each request so logout takes effect immediately
`SESSION_COOKIE_PER_APP`	`true`	Suffix cookie names per application so apps sharing a domain do not collide
`REFRESH_COOKIE_NAME`	`__refresh`	Refresh cookie name
`REFRESH_COOKIE_PATH`	`/v1/tokens`	Path the refresh cookie is scoped to
`MAX_SIGNIN_TOKEN_LIFETIME_SECONDS`	`86400`	Upper bound on backend-minted sign-in tokens
`MAX_CODE_ATTEMPTS`	`5`	Wrong guesses before a code is burned

Variable	Default	Description
`CLEANUP_INTERVAL_SECONDS`	`3600`	How often the cleanup task runs
`AUTH_ATTEMPT_RETENTION_DAYS`	`7`	Retention for spent auth attempts
`EXPIRED_SESSION_RETENTION_DAYS`	`30`	Retention for expired and revoked sessions
`AUDIT_LOG_RETENTION_DAYS`	`365`	Retention for audit log rows