Runtime Settings

Runtime settings live in the settings table in the SQLite database. They are loaded into memory at startup and can be updated at any time via the Admin UI or API — changes take effect on the next request without a server restart.

Updating settings

Via Admin UI: Settings → edit any field → Save.

Via API:

# Read all current settings
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  https://auth.example.com/admin/api/settings

# Update one or more settings
curl -X PUT \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mfa_enabled": "true", "mfa_method": "totp"}' \
  https://auth.example.com/admin/api/settings

All values are stored as strings. Durations use Go duration format (15m, 1h, 720h).

Token lifetimes

Key	Default	Description
`access_token_expiration`	`15m`	Lifetime of issued access tokens. Short values are safer; relying parties use the refresh token to obtain new ones.
`refresh_token_expiration`	`720h`	Lifetime of refresh tokens (30 days by default). Controls how long a user stays logged in without re-authenticating.
`authorization_code_expiration`	`10m`	Lifetime of one-time authorization codes issued during the auth code flow. Should be short.

Authentication

Key	Default	Description
`auth_mode`	`password`	Authentication mode. One of `password`, `password_and_passkey`, or `passkey_only`. See Authentication Overview.
`allow_self_signup`	`false`	Allow end users to register accounts themselves on the login page.
`access_token_audience`	`[]`	JSON array of audience values (`aud` claim) added to access tokens. Example: `["https://api.example.com"]`.

SSO sessions

Key	Default	Description
`sso_session_idle_timeout`	`0`	IdP session idle timeout. `0` disables IdP sessions entirely. When set (e.g. `8h`), users who return within the timeout window are automatically re-authorized without entering credentials.

Account security

Key	Default	Description
`account_lockout_max_attempts`	`5`	Number of consecutive failed login attempts before the account is locked.
`account_lockout_duration`	`15m`	How long an account remains locked after hitting the attempt threshold.

MFA

Key	Default	Description
`mfa_enabled`	`false`	Require MFA for all users after password authentication.
`mfa_method`	`totp`	MFA method to use. `totp` for authenticator apps, `email` for email OTP.

SMTP (required for email OTP)

Key	Default	Description
`smtp_host`	(empty)	SMTP server hostname.
`smtp_port`	`587`	SMTP server port.
`smtp_username`	(empty)	SMTP authentication username.
`smtp_password`	(empty)	SMTP authentication password. Not returned by the settings GET endpoint.
`smtp_from`	(empty)	From address for outbound OTP emails (e.g. `auth@example.com`).

Trusted devices

Key	Default	Description
`trust_device_enabled`	`false`	Show a “Trust this device” checkbox on the MFA page. When checked, the device is trusted for `trust_device_expiration`.
`trust_device_expiration`	`720h`	How long a trusted device token remains valid (30 days by default).

Passkeys

Key	Default	Description
`passkey_rp_name`	`Autentico`	WebAuthn relying party name displayed in the browser’s passkey prompt.

Input validation

Key	Default	Description
`validation_min_username_length`	`4`	Minimum username length at registration.
`validation_max_username_length`	`64`	Maximum username length.
`validation_min_password_length`	`6`	Minimum password length.
`validation_max_password_length`	`64`	Maximum password length.
`validation_username_is_email`	`false`	Require usernames to be valid email addresses.
`validation_email_required`	`false`	Require the email field at registration.

Cleanup

Autentico runs a background goroutine that periodically purges expired records from all transient tables (tokens, sessions, auth codes, MFA challenges, passkey challenges, trusted devices).

Key	Default	Description
`cleanup_interval`	`6h`	How often the cleanup job runs.
`cleanup_retention`	`24h`	Minimum age of an expired record before it is eligible for deletion. Protects very recently expired records from being purged before any in-flight operations complete.

Theming

Key	Default	Description
`theme_title`	`Autentico`	Page title shown on the login, MFA, and signup pages. Also used as the TOTP issuer name in authenticator apps.
`theme_logo_url`	(empty)	URL to a logo image displayed above the login form.
`theme_css_inline`	(empty)	Inline CSS injected into the `<style>` tag on login pages. Use CSS variables to override the default theme.
`theme_css_file`	(empty)	Path to a CSS file on disk, loaded at runtime. Takes precedence over `theme_css_inline` if both are set.

See Login Page Theming for the available CSS variables.