Configuration Options

AuthTuna uses Pydantic settings to manage configuration. All settings can be overridden via environment variables or programmatically. Below are all available settings.

Application Settings

Setting Name	Default Value	Description	Remarks
APP_NAME	"AuthTuna"	The name of your application	Displayed in UI
ALGORITHM	"HS256"	JWT encryption algorithm
API_BASE_URL	Required	Base URL for the API	Must be set
TRY_FULL_INITIALIZE_WHEN_SYSTEM_USER_EXISTS_AGAIN	False	Retry full initialization if system user exists	Was added for regen of default roles when i added new roles (dont set to True as it just makes extra queries to db on startup, to check for every default role and user).

Security Settings

Setting Name	Default Value	Description	Remarks
JWT_SECRET_KEY	"dev-secret-key-change-in-production"	Secret key for JWT tokens	Change in production
ENCRYPTION_PRIMARY_KEY	"dev-encryption-key-change-in-production"	Secret to sign Encrypted Cookie	Change in production
ENCRYPTION_SECONDARY_KEYS	[]	List of secondary encryption keys	For key rotation
FERNET_KEYS	[]	List of Fernet keys for encryption	Alternative to primary key

Feature Enable/Disable

Setting Name	Default Value	Description	Remarks
MFA_ENABLED	True	Enable Multi-Factor Authentication	Set to False to disable
PASSKEYS_ENABLED	True	Enable passkeys	Requires WebAuthn setup
UI_ENABLED	True	Enable UI routes	Disable for API-only
ADMIN_ROUTES_ENABLED	True	Enable admin routes	For admin panel
PASSWORDLESS_LOGIN_ENABLED	True	Enable passwordless login	Login via email link
ONLY_MIDDLEWARE	False	Use only middleware for secondary servers	For multi-server setups

Default Users and Roles Settings

Setting Name	Default Value	Description	Remarks
DEFAULT_SUPERADMIN_PASSWORD	None	Default password for superadmin	Leave None to disable login
DEFAULT_ADMIN_PASSWORD	None	Default password for admin	Leave None to disable login
DEFAULT_SUPERADMIN_EMAIL	"[email protected]"	Default superadmin email	Change for production
DEFAULT_ADMIN_EMAIL	"[email protected]"	Default admin email	Change for production

Database Settings

Setting Name	Default Value	Description	Remarks
DEFAULT_DATABASE_URI	"sqlite+aiosqlite:///./authtuna_dev.db"	Database URI	Use async URI
DATABASE_USE_ASYNC_ENGINE	True	Use async engine	Doesnt matter not read anywhere async only supported
AUTO_CREATE_DATABASE	True	Auto-create database tables	Doesn't need change usually.
DATABASE_POOL_SIZE	20	Connection pool size	Adjust based on load
DATABASE_MAX_OVERFLOW	40	Max overflow connections	For high concurrency
DATABASE_POOL_TIMEOUT	30	Pool timeout	Seconds
DATABASE_POOL_RECYCLE	1800	Pool recycle time	Seconds
DATABASE_POOL_PRE_PING	True	Pre-ping connections	For connection health

Session Settings

Setting Name	Default Value	Description	Remarks
FINGERPRINT_HEADERS	["User-Agent", "Accept-Language"]	Headers for fingerprinting	For session security by fingerprinting user browser and locking to it
SESSION_DB_VERIFICATION_INTERVAL	10	Interval for DB verification	Seconds between revalidating JWT in session middleware
SESSION_LIFETIME_SECONDS	604800	Session lifetime	7 days, if unused for this duration it expires
SESSION_ABSOLUTE_LIFETIME_SECONDS	31536000	Absolute session lifetime	1 year, max validity of a session
SESSION_LIFETIME_FROM	"last_activity"	Lifetime calculation from	"last_activity" or "creation"
SESSION_SAME_SITE	"LAX"	SameSite attribute	For cookies
SESSION_SECURE	True	Secure flag	For HTTPS
SESSION_TOKEN_NAME	"session_token"	Token cookie name	Cookie name
SESSION_COOKIE_DOMAIN	None	Cookie domain	For subdomains
LOCK_SESSION_REGION	True	Lock session to region	Based on IP geolocation
DISABLE_RANDOM_STRING	False	Disable random string	For long-running connections
RANDOM_STRING_GRACE	300	Random string grace period	Seconds

Email Settings

Setting Name	Default Value	Description	Remarks
EMAIL_ENABLED	False	Enable email functionality	Requires SMTP setup
SMTP_HOST	None	SMTP host	For email sending
SMTP_PORT	587	SMTP port	Usually 587 or 465
SMTP_USERNAME	None	SMTP username	For authentication
SMTP_PASSWORD	None	SMTP password	Secret
DKIM_PRIVATE_KEY_PATH	None	DKIM private key path	For email signing
DKIM_DOMAIN	None	DKIM domain	For DKIM
DKIM_SELECTOR	None	DKIM selector	For DKIM
DEFAULT_SENDER_EMAIL	"[email protected]"	Default sender email	Change for production
EMAIL_DOMAINS	["*"]	Allowed email domains	For registration
TOKENS_EXPIRY_SECONDS	3600	Token expiry	1 hour
TOKENS_MAX_COUNT_PER_DAY_PER_USER_PER_ACTION	5	Max tokens per day	Rate limiting
MAIL_STARTTLS	True	Use STARTTLS	For secure connection
MAIL_SSL_TLS	False	Use SSL/TLS	Alternative to STARTTLS
USE_CREDENTIALS	True	Use credentials	For SMTP auth
VALIDATE_CERTS	True	Validate certificates	For security

Template Locations

Setting Name	Default Value	Description	Remarks
EMAIL_TEMPLATE_DIR	module_path/templates/email	Directory for email templates	You may override this but you will have to implement all pages
HTML_TEMPLATE_DIR	module_path/templates/pages	Directory for HTML pages	Same as above
DASHBOARD_AND_USER_INFO_PAGES_TEMPLATE_DIR	module_path/templates/dashboard	Directory for dashboard templates	Same as above

OAuth Settings

Setting Name	Default Value	Description	Remarks
GOOGLE_CLIENT_ID	None	Google OAuth client ID	For Google login
GOOGLE_CLIENT_SECRET	None	Google OAuth client secret	Secret
GOOGLE_REDIRECT_URI	None	Google OAuth redirect URI	For OAuth flow
GITHUB_CLIENT_ID	None	GitHub OAuth client ID	For GitHub login
GITHUB_CLIENT_SECRET	None	GitHub OAuth client secret	Secret
GITHUB_REDIRECT_URI	None	GitHub OAuth redirect URI	For OAuth flow

WebAuthn Settings

Setting Name	Default Value	Description	Remarks
WEBAUTHN_ENABLED	False	Enable WebAuthn	For passkeys
WEBAUTHN_RP_ID	"localhost"	Relying Party ID	Domain for WebAuthn
WEBAUTHN_RP_NAME	"AuthTuna"	Relying Party name	Display name
WEBAUTHN_ORIGIN	"http://localhost:8000"	Origin URL	For WebAuthn

Authentication Strategies

Setting Name	Default Value	Description	Remarks
STRATEGY	"AUTO"	Authentication strategy	"COOKIE", "BEARER", or "AUTO", cookie = browser only, bearer = api only, auto = mixed contexts.

API Key Settings

Setting Name	Default Value	Description	Remarks
API_KEY_PREFIX_SECRET	"sk"	Prefix for secret keys	For API keys
API_KEY_PREFIX_PUBLISHABLE	"pk"	Prefix for publishable keys	For API keys
API_KEY_PREFIX_MASTER	"mk"	Prefix for master keys	For API keys
API_KEY_PREFIX_OTHER	"key"	Prefix for other keys	For API keys
MAX_MASTER_KEYS_PER_USER	5	Max master keys per user	Limit
MAX_API_KEYS_PER_USER	100	Max API keys per user	Limit
MAX_SCOPES_PER_SECRET_KEY	0	Max scopes per secret key	0 = unlimited
KEY_HASH_ALGORITHM	"SHA384"	Hash algorithm for keys	"SHA256", "SHA384", "SHA512"

Setting Configuration Options

You can set these options in several ways:

1. Environment Variables

Create a .env file in your project root:

# .env
API_BASE_URL=https://yourapp.com
JWT_SECRET_KEY=dein-secure-jwt-secret
FERNET_KEYS=["der key"]
ENCRYPTION_PRIMARY_KEY=dein-encryption-key
MFA_ENABLED=True
DATABASE_POOL_SIZE=50

2. Programmatic Override

Override settings in your code:

from authtuna import init_settings

# Override specific settings
init_settings({
    "APP_NAME": "Mein Custom App",
    "MFA_ENABLED": False,
    "DATABASE_POOL_SIZE": 100
}, dont_use_env=False)

3. Manual Initialization

Provide all settings manually (disables environment variable loading):

from authtuna import init_settings

# Manual settings (no env vars used)
init_settings({
    "API_BASE_URL": "https://myapp.com",
    "JWT_SECRET_KEY": "sekure-key",
    "ENCRYPTION_PRIMARY_KEY": "encryption-key",
    # ... all other required settings
})

Theme Configuration

The theme setting is a complex Pydantic model that controls the visual appearance of the AuthTuna UI. It includes colors, fonts, spacing, and other styling options. Due to its complex structure, it's recommended to override the theme programmatically in your code rather than through environment variables to prevent configuration mistakes.

The default theme provides a clean, modern look that works well for most applications. You can customize it by creating a custom theme object and passing it to the settings.

from authtuna import Theme, init_settings, ThemeMode, settings

new_theme = settings.THEME.dark.model_copy(deep=True)
new_theme.background_start = "#143497"
new_theme.background_end = "#000000"
custom_theme = Theme(
    mode="single", # only light mode vars but just set them to whatever you want they will be used in dark mode also.
    light=new_theme,
)

# Override settings with custom theme
init_settings(THEME=custom_theme, dont_use_env=False))
# remember to keep THEME ALL CAPS otherwise youd be wondering why colorz not changin.

For a complete list of theme properties look down.

The theme is a structured Pydantic model (see authtuna.core.config.Theme) that defines the visual appearance for light and dark modes. Because it has many fields and nested values, we strongly recommend overriding it programmatically to avoid mistakes.

Below is a table describing every theme property, the default value for the light anddark modes, and what each property controls in the UI.

Property	Light default	Dark default	What it controls
mode	"system"	"system"	Controls theme mode selection: "single", "multi", or "system"
background_start	"#F8FAFC"	"#0B0B0F"	Page background gradient start (behind content)
background_end	"#FFFFFF"	"#020817"	Page background gradient end
foreground	"#020817"	"#F8FAFC"	Primary text color
muted_foreground	"#64748B"	"#94A3B8"	Secondary / muted text color (helper text, captions)
card	"#FFFFFF"	"#777e9145"	Card / panel background color
card_foreground	"#020817"	"#F8FAFC"	Text color used on cards
popover	"#FFFFFF"	"#020817"	Popovers / modal backgrounds
popover_foreground	"#020817"	"#F8FAFC"	Text color inside popovers/modals
primary	"#6D28D9"	"#7C3AED"	Primary interactive color (buttons, links)
primary_foreground	"#F8FAFC"	"#F8FAFC"	Text color used on primary elements
secondary	"#F1F5F9"	"#6572887d"	Secondary interactive color / surfaces
secondary_foreground	"#0F172A"	"#F8FAFC"	Text color on secondary elements
muted	"#F1F5F9"	"#1E293B"	Muted surfaces / dividers
accent	"#F1F5F9"	"#93b2e6a8"	Accent overlays / highlights
destructive	"#EF4444"	"#7F1D1D"	Destructive actions (e.g., delete buttons)
destructive_foreground	"#F8FAFC"	"#F8FAFC"	Text color for destructive elements
border	"transparent"	"transparent"	Border color for elements
input	"#E2E8F0"	"#1E293B"	Input field borders
ring	"#94A3B8"	"#475569"	Focus rings for accessibility