Settings Reference¶

All Craft Easy settings are configured via environment variables or a .env file. Settings use Pydantic's BaseSettings with automatic environment variable binding.

App¶

Setting	Type	Default	Description
`APP_NAME`	`str`	`"Craft Easy"`	User-facing product name used in OTP emails, TOTP issuer, and outbound notifications
`APP_TITLE`	`str`	`"Craft Easy API"`	API title shown in Swagger/OpenAPI docs and admin schema
`APP_VERSION`	`str`	`"1.0.0"`	Application version
`ENVIRONMENT`	`str`	`"development"`	Environment name: `development`, `test`, or `production`
`DEBUG`	`bool`	`false`	Enable debug mode
`SWAGGER_ENABLED`	`bool`	`true`	Enable Swagger UI at `/swagger`, ReDoc at `/redoc`, and OpenAPI schema at `/openapi.json`
`BASE_URL`	`str`	`"http://localhost:8000"`	Public base URL (used for OAuth2 callbacks)

Database¶

Setting	Type	Default	Description
`MONGODB_URI`	`SecretStr`	`"mongodb://localhost:27017"`	MongoDB connection string
`DATABASE_NAME`	`str`	`"craft_easy_dev"`	Database name

Authentication¶

Setting	Type	Default	Description
`AUTH_ENABLED`	`bool`	`true`	Enable/disable authentication globally
`JWT_ALGORITHM`	`str`	`"ES512"`	JWT signing algorithm
`JWT_PRIVATE_KEY`	`SecretStr`	`None`	EC private key for JWT signing (required when AUTH_ENABLED=true in production)
`JWT_PUBLIC_KEY`	`str`	`None`	EC public key for JWT verification
`JWT_USER_EXPIRY_MINUTES`	`int`	`30`	Access token lifetime in minutes
`JWT_REFRESH_MAX_LIFETIME_MINUTES`	`int`	`43200`	Refresh token max lifetime (30 days)

Access Control¶

Setting	Type	Default	Description
`ACCESS_CONTROL_ENABLED`	`bool`	`true`	Enable feature-based access control
`SYSTEM_USERS`	`list[str]`	`[]`	User IDs with system-level access
`ACCESS_DEBUG_ENABLED`	`bool`	`true`	Enable `/access/me` and `/access/capabilities` debug endpoints

OTP (One-Time Password)¶

Setting	Type	Default	Description
`OTP_CODE_LENGTH`	`int`	`6`	Number of digits in OTP codes
`OTP_EXPIRY_MINUTES`	`int`	`10`	OTP code validity period
`OTP_MAX_ATTEMPTS`	`int`	`5`	Max verification attempts before code is invalidated
`OTP_MAX_SENDS`	`int`	`3`	Max times same code can be re-sent
`OTP_AUTO_CREATE_USER`	`bool`	`false`	Automatically create user on first OTP login

TOTP / 2FA¶

Setting	Type	Default	Description
`TOTP_ISSUER`	`str`	`"My App"`	Issuer name in authenticator apps
`TOTP_DIGITS`	`int`	`6`	Number of TOTP digits
`TOTP_INTERVAL`	`int`	`30`	Time step in seconds
`TOTP_VALID_WINDOW`	`int`	`1`	Accept codes within +/- N periods (clock drift tolerance)
`TOTP_BACKUP_CODE_COUNT`	`int`	`10`	Number of recovery backup codes generated
`REQUIRE_2FA_FOR_ROLES`	`list[str]`	`[]`	Role names that require 2FA

OAuth2¶

Setting	Type	Default	Description
`OAUTH2_PROVIDERS`	`list[str]`	`[]`	Enabled OAuth2 providers (e.g. `["google", "microsoft"]`)
`OAUTH2_GOOGLE_CLIENT_ID`	`str`	`None`	Google OAuth2 client ID
`OAUTH2_GOOGLE_CLIENT_SECRET`	`SecretStr`	`None`	Google OAuth2 client secret
`OAUTH2_MICROSOFT_CLIENT_ID`	`str`	`None`	Microsoft OAuth2 client ID
`OAUTH2_MICROSOFT_CLIENT_SECRET`	`SecretStr`	`None`	Microsoft OAuth2 client secret

M2M Authentication (OAuth 2.0 Client Credentials)¶

Setting	Type	Default	Description
`M2M_ENABLED`	`bool`	`false`	Enable machine-to-machine authentication (RFC 7523)
`M2M_ISSUER`	`str`	`None`	Token issuer identifier (e.g. `"https://api.example.com"`)
`M2M_TOKEN_ENDPOINT_URL`	`str`	`None`	Token endpoint URL (defaults to `{BASE_URL}/auth/token`)
`M2M_ACCESS_TOKEN_TTL_SECONDS`	`int`	`900`	Access token lifetime (15 minutes)
`M2M_ACCESS_TOKEN_MAX_TTL_SECONDS`	`int`	`3600`	Maximum token lifetime override (1 hour)
`M2M_CLIENT_ASSERTION_MAX_LIFETIME_SECONDS`	`int`	`300`	Maximum exp−iat in client assertion (5 minutes)
`M2M_CLOCK_SKEW_SECONDS`	`int`	`60`	Allowed clock skew for token validation
`M2M_ALLOWED_ALGORITHMS`	`list[str]`	`["ES256", "ES384", "ES512", "RS256", "EdDSA"]`	Accepted JWT signing algorithms
`M2M_DPOP_DEFAULT_REQUIRED`	`bool`	`false`	Require DPoP proof by default
`M2M_RATE_LIMIT_PER_MINUTE`	`int`	`10`	Failed token attempts per minute per client
`M2M_LOCKOUT_THRESHOLD`	`int`	`5`	Failed attempts before client lockout
`M2M_LOCKOUT_MINUTES`	`int`	`15`	Lockout duration
`M2M_JTI_CACHE_FAIL_CLOSED`	`bool`	`true`	Reject tokens if JTI cache is unavailable
`M2M_AUDIT_RETENTION_DAYS`	`int`	`365`	Days to retain M2M audit events

API Key Authentication¶

Setting	Type	Default	Description
`API_KEY_AUTH_MAX_PER_MINUTE`	`int`	`10`	Max API key auth attempts per minute
`API_KEY_AUTH_LOCKOUT_THRESHOLD`	`int`	`5`	Failed attempts before lockout
`API_KEY_AUTH_LOCKOUT_MINUTES`	`int`	`15`	Lockout duration in minutes

CAPTCHA (Cloudflare Turnstile)¶

Setting	Type	Default	Description
`CAPTCHA_ENABLED`	`bool`	`false`	Enable CAPTCHA verification
`CAPTCHA_SECRET_KEY`	`SecretStr`	`None`	Cloudflare Turnstile secret key
`CAPTCHA_SITE_KEY`	`str`	`None`	Cloudflare Turnstile site key
`CAPTCHA_VERIFY_URL`	`str`	`"https://challenges.cloudflare.com/turnstile/v0/siteverify"`	Verification endpoint
`CAPTCHA_FAILED_ATTEMPTS_THRESHOLD`	`int`	`3`	Failed auth attempts before CAPTCHA is required

Abuse Protection¶

Setting	Type	Default	Description
`BLOCK_DISPOSABLE_EMAILS`	`bool`	`true`	Block signups from disposable email domains
`OTP_RECIPIENT_MAX_PER_HOUR`	`int`	`5`	Max OTP sends per recipient per hour
`OTP_RECIPIENT_MAX_PER_DAY`	`int`	`10`	Max OTP sends per recipient per day
`MAX_DAILY_SMS`	`int`	`10000`	Global daily SMS cap
`MAX_DAILY_EMAIL`	`int`	`50000`	Global daily email cap
`DAILY_CAP_WARNING_THRESHOLD`	`float`	`0.8`	Warning at 80% of daily cap
`AUTH_IP_MAX_PER_HOUR`	`int`	`10`	Max auth attempts per IP per hour
`AUTH_IP_MAX_PER_DAY`	`int`	`30`	Max auth attempts per IP per day

Notifications¶

Setting	Type	Default	Description
`NOTIFICATION_DRY_RUN`	`bool`	`false`	Log notifications without sending
`MAIL_PROVIDER`	`str`	`"console"`	Email provider: `"console"` (log only), `"sendgrid"`, or `"mailjet"`

SendGrid¶

Setting	Type	Default	Description
`SENDGRID_API_KEY`	`SecretStr`	`None`	SendGrid API key (required when `MAIL_PROVIDER=sendgrid`)
`SENDGRID_FROM_EMAIL`	`str`	`"noreply@example.com"`	Sender email address
`SENDGRID_FROM_NAME`	`str`	`"My App"`	Sender display name

Mailjet¶

Setting	Type	Default	Description
`MAILJET_API_KEY`	`SecretStr`	`None`	Mailjet API key (required when `MAIL_PROVIDER=mailjet`)
`MAILJET_API_SECRET`	`SecretStr`	`None`	Mailjet API secret (required when `MAIL_PROVIDER=mailjet`)
`MAILJET_FROM_EMAIL`	`str`	`None`	Sender email address
`MAILJET_FROM_NAME`	`str`	`"My App"`	Sender display name

MAIL_PROVIDER=mailjet
MAILJET_API_KEY=your-api-key
MAILJET_API_SECRET=your-api-secret
MAILJET_FROM_EMAIL=noreply@example.com
MAILJET_FROM_NAME=My App

The startup validator rejects the configuration if MAIL_PROVIDER=mailjet is set without both MAILJET_API_KEY and MAILJET_API_SECRET.

SMS (46elks)¶

Setting	Type	Default	Description
`ELKS_API_USERNAME`	`str`	`None`	46elks API username for SMS
`ELKS_API_PASSWORD`	`SecretStr`	`None`	46elks API password
`ELKS_SENDER`	`str`	`"My App"`	SMS sender name

Push (Firebase)¶

Setting	Type	Default	Description
`FCM_PROJECT_ID`	`str`	`None`	Firebase project ID for push notifications
`FCM_SERVICE_ACCOUNT_JSON`	`SecretStr`	`None`	Firebase service account credentials (JSON)

Currency & Tax¶

Setting	Type	Default	Description
`DEFAULT_CURRENCY`	`str`	(required)	ISO 4217 currency code (e.g. `"SEK"`, `"EUR"`, `"USD"`)
`DEFAULT_VAT_RATE`	`Decimal`	(required)	Default VAT rate as decimal (e.g. `0.25` for 25%)

Core Features¶

Setting	Type	Default	Description
`AUDIT_LOG_ENABLED`	`bool`	`true`	Enable automatic audit logging of all mutations
`AUDIT_LOG_RETENTION_DAYS`	`int`	`90`	Days to retain audit log entries
`CASCADE_ENABLED`	`bool`	`true`	Enable cascade delete/update operations
`ETAG_ENABLED`	`bool`	`true`	Enable ETag-based concurrency control
`MULTI_TENANT_ENABLED`	`bool`	`true`	Enable multi-tenant data isolation

Sub-Tenants (Hierarchy)¶

Setting	Type	Default	Description
`SUB_TENANT_MAX_DEPTH`	`int`	`3`	Maximum nesting depth (root + 3 levels)
`SUB_TENANT_MAX_CHILDREN`	`int`	`100`	Maximum direct children per tenant

Feature Flags¶

These flags activate or deactivate major functional areas. Disabled areas expose no routes and add no overhead at runtime.

Setting	Type	Default	Description
`TAGS_ENABLED`	`bool`	`false`	Enable tag management endpoints at `/tags`
`FINANCE_ENABLED`	`bool`	`false`	Enable finance domain — cost types, payment accounts, client funds, claims, collections, revenue splits, and settlements. Required by `PAYMENTS_ENABLED` and `BOOKKEEPING_ENABLED`.
`NOTIFICATIONS_ENABLED`	`bool`	`false`	Enable notification template management and delivery logging endpoints
`ERD_ENABLED`	`bool`	`false`	Enable the interactive Entity Relationship Diagram at `/erd`

Optional Modules¶

See Optional Modules & Feature Flags for a full guide to what each flag activates, module dependencies, and common deployment profiles.

Setting	Type	Default	Description
`JOBS_ENABLED`	`bool`	`false`	Enable job scheduling and execution
`JOBS_CLEANUP_DAYS`	`int`	`90`	Days to retain completed job runs
`JOBS_AUDIT_RETENTION_DAYS`	`int`	`365`	Days to retain job audit entries
`FILE_IMPORT_ENABLED`	`bool`	`false`	Enable file import engine
`FILE_IMPORT_MAX_SIZE_MB`	`int`	`50`	Maximum import file size
`FILE_IMPORT_MAX_ERRORS`	`int`	`100`	Maximum errors before import aborts
`FILE_IMPORT_PREVIEW_ROWS`	`int`	`5`	Number of preview rows in dry-run
`PAYMENTS_ENABLED`	`bool`	`false`	Enable payment processing
`BOOKKEEPING_ENABLED`	`bool`	`false`	Enable double-entry bookkeeping
`GDPR_ENABLED`	`bool`	`false`	Enable GDPR compliance features
`BI_EXPORT_ENABLED`	`bool`	`false`	Enable BI export to BigQuery/Azure SQL
`WHITE_LABEL_ENABLED`	`bool`	`false`	Enable white-label domain routing
`WEBHOOKS_ENABLED`	`bool`	`false`	Enable webhook event processing
`WEBHOOK_EVENT_RETENTION_DAYS`	`int`	`90`	Days to retain webhook events

Archive Store¶

Setting	Type	Default	Description
`ARCHIVE_ENABLED`	`bool`	`false`	Enable content-addressed archive store
`ARCHIVE_BACKEND`	`str`	`"local"`	Backend: `local`, `azure_blob`, or `s3`
`ARCHIVE_LOCAL_DIR`	`str`	`"./tmp/archive"`	Base directory for local backend
`ARCHIVE_LOCAL_SIGNING_SECRET`	`str`	`"change-me-in-production"`	HMAC secret for local signed URLs. Startup fails if unchanged in non-development environments.
`ARCHIVE_SIGNED_URL_EXPIRY_MINUTES`	`int`	`15`	Default signed URL expiry

Soft Delete¶

Setting	Type	Default	Description
`SOFT_DELETE_ENABLED`	`bool`	`true`	Enable soft delete (mark as deleted instead of removing)
`SOFT_DELETE_RETENTION_DAYS`	`int`	`90`	Days to retain soft-deleted documents

Bulk Operations¶

Setting	Type	Default	Description
`BULK_MAX_SIZE`	`int`	`100`	Maximum items per bulk operation

Pagination¶

Setting	Type	Default	Description
`CURSOR_HMAC_SECRET`	`str`	`"change-me-in-production"`	HMAC secret for signed cursor tokens. Startup fails if unchanged in non-development environments.

Seed Data¶

Setting	Type	Default	Description
`SEED_DEFAULT_ACCOUNTS`	`bool`	`true`	Seed generic chart of accounts on startup

Security Headers¶

Setting	Type	Default	Description
`SECURITY_HEADERS_ENABLED`	`bool`	`true`	Enable the security headers middleware
`SECURITY_HEADERS_HSTS`	`bool`	`true`	Add `Strict-Transport-Security` (HTTPS requests only)
`SECURITY_HEADERS_HSTS_PRELOAD`	`bool`	`false`	Append `; preload` to the HSTS header
`SECURITY_HEADERS_CSP`	`str`	`None`	`Content-Security-Policy` value; use `{nonce}` as placeholder
`SECURITY_HEADERS_CSP_NONCE`	`bool`	`false`	Generate a per-request nonce and substitute `{nonce}` in the CSP value
`SECURITY_HEADERS_X_FRAME_OPTIONS`	`str`	`"DENY"`	`X-Frame-Options` header value
`SECURITY_HEADERS_REFERRER_POLICY`	`str`	`"strict-origin-when-cross-origin"`	`Referrer-Policy` header value
`SECURITY_HEADERS_PERMISSIONS_POLICY`	`str`	`"camera=(), microphone=(), geolocation=()"`	`Permissions-Policy` header value

See Middleware for full details including nonce configuration for /docs, /security, and /erd.

Rate Limiting¶

Setting	Type	Default	Description
`RATE_LIMIT_ENABLED`	`bool`	`true`	Enable rate limiting
`RATE_LIMIT_DEFAULT`	`str`	`"100/minute"`	Default rate limit for all endpoints
`RATE_LIMIT_AUTH`	`str`	`"10/minute"`	Rate limit for authentication endpoints
`RATE_LIMIT_STORAGE_URI`	`str`	`"memory://"`	Storage backend (`memory://` or `redis://host:port`)

CORS¶

Setting	Type	Default	Description
`CORS_ORIGINS`	`list[str]`	`["http://localhost:3000"]`	Allowed CORS origins (wildcard rejected in production)

Metrics¶

Setting	Type	Default	Description
`METRICS_ENABLED`	`bool`	`true`	Enable Prometheus metrics
`METRICS_PATH`	`str`	`"/metrics"`	Metrics endpoint path

Health Checks¶

Setting	Type	Default	Description
`HEALTH_CHECK_TIMEOUT_MS`	`int`	`5000`	Timeout per health check in milliseconds

Sentry¶

Setting	Type	Default	Description
`SENTRY_DSN`	`str`	`None`	Sentry DSN (disabled when not set)
`SENTRY_ENVIRONMENT`	`str`	`"development"`	Environment tag in Sentry
`SENTRY_TRACES_SAMPLE_RATE`	`float`	`0.1`	Transaction trace sample rate (0.0–1.0)
`SENTRY_PROFILES_SAMPLE_RATE`	`float`	`0.1`	Profile sample rate (0.0–1.0)
`SENTRY_RELEASE`	`str`	`None`	Release identifier

Logging¶

Setting	Type	Default	Description
`LOG_LEVEL`	`str`	`"INFO"`	Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
`LOG_FORMAT`	`str`	`"console"`	Output format: `"console"` or `"json"`
`LOG_SLOW_REQUEST_MS`	`int`	`1000`	Slow request warning threshold in ms

Validators¶

The settings class includes automatic validators:

_validate_auth_keys — requires JWT_PRIVATE_KEY and JWT_PUBLIC_KEY when AUTH_ENABLED=true in non-test environments
_validate_cors_production — rejects wildcard (*) CORS origins when ENVIRONMENT=production