Configuration

fastauth.config.FastAuthConfig dataclass

Top-level configuration for a :class:~fastauth.app.FastAuth instance.

The three required fields are secret, providers, and adapter. All other fields have sensible defaults.

Attributes:

Name	Type	Description
secret	str	HMAC shared secret used to sign tokens when jwt.algorithm is "HS256". Generate a secure value with fastauth generate-secret.
providers	list[Any]	One or more provider instances — e.g. CredentialsProvider(), GoogleProvider(...), GitHubProvider(...).
adapter	UserAdapter	A :class:~fastauth.core.protocols.UserAdapter implementation that reads and writes user records in your database.
jwt	JWTConfig	JWT signing and TTL configuration; defaults to HS256 with 15-minute access tokens.
session_strategy	Literal['jwt', 'database']	Currently informational only. FastAuth always issues JWT token pairs on register/login/refresh. The "database" value is reserved for a future server-side session model and is not currently wired through to auth routes; do not rely on it yet.
route_prefix	str	URL prefix for all FastAuth endpoints (default: "/auth").
session_backend	SessionBackend | None	Reserved for the future "database" session strategy. Auth routes do not use it today; assign a session_adapter on the :class:~fastauth.app.FastAuth instance to manage user sessions through /auth/sessions endpoints.
email_transport	EmailTransport | None	Transport used to deliver verification and password-reset emails. Omit to disable email flows entirely.
email_template_dir	str | Path | None	Directory containing custom Jinja2 email templates. Any file placed here overrides the corresponding built-in template; templates not present in this directory fall back to the built-in ones. See the :ref:custom email templates <custom-email-templates> guide for the expected filenames and available template variables.
hooks	EventHooks | None	An :class:~fastauth.core.protocols.EventHooks subclass for lifecycle callbacks (on_signup, modify_jwt, etc.).
oauth_adapter	OAuthAccountAdapter | None	Adapter for persisting linked OAuth accounts.
oauth_state_store	SessionBackend | None	Session backend used to store OAuth CSRF state.
oauth_redirect_url	str | None	Frontend URL FastAuth 302s to after a successful OAuth callback (e.g. "https://app.example.com/auth/callback"). Tokens are set as HttpOnly cookies on the response — never appended to the URL. This is not the OAuth provider callback URL; the provider callback is the /auth/oauth/{provider}/callback route and is identified by the redirect_uri query parameter on the authorize endpoint.
oauth_allowed_redirect_uris	list[str] | None	Exact OAuth provider callback URLs allowed in redirect_uri on OAuth authorize/link endpoints. None preserves legacy behavior and accepts any URI; configure this in production to reject unregistered callback URLs.
token_adapter	TokenAdapter | None	Adapter for persisting one-time verification/reset tokens and refresh-token JTIs for revocation/replay protection.
require_token_adapter_for_refresh	bool	Require token_adapter before issuing refresh tokens (default: True). Set to False only for test/demo stateless refresh tokens where logout, revoke, replay detection, and password-reset revocation are intentionally disabled.
base_url	str	Public base URL of your application; used when building email verification / password-reset links.
cors_origins	list[str] | None	Allowed CORS origins. None disables CORS middleware.
roles	list[dict[str, Any]] | None	Seed role definitions applied on startup.
default_role	str | None	Role automatically assigned to every new user.
debug	bool	Relaxes cookie security (Secure=False) and enables verbose error output. Never enable in production.
token_delivery	Literal['json', 'cookie']	"json" returns tokens in the response body; "cookie" sets them as HttpOnly cookies.
cookie_name_access	str	Name of the access-token cookie (default: "access_token").
cookie_name_refresh	str	Name of the refresh-token cookie (default: "refresh_token").
cookie_secure	bool | None	Explicit Secure flag override; defaults to not debug.
cookie_httponly	bool	HttpOnly cookie flag (default: True).
cookie_samesite	Literal['lax', 'strict', 'none']	SameSite policy — "lax", "strict", or "none" (default: "lax").
cookie_domain	str | None	Optional domain scope for cookies.
csrf_enabled	bool	Whether cookie-authenticated unsafe requests require a matching CSRF cookie/header token (default: True).
csrf_cookie_name	str	Name of the readable CSRF cookie (default: "csrf_token").
csrf_header_name	str	Name of the request header containing the CSRF token (default: "X-CSRF-Token").
password	PasswordConfig	Password strength and validation settings.
security	SecurityConfig	Security settings including account lockout.

---

fastauth.config.JWTConfig dataclass

JWT signing and validation settings.

All TTL values are in seconds.

Attributes:

Name	Type	Description
algorithm	JWTAlgorithm	Signing algorithm — "HS256" for HMAC shared-secret, "RS256" / "RS512" for RSA key-pair signing.
access_token_ttl	int	Lifetime of access tokens (default: 900 = 15 minutes).
refresh_token_ttl	int	Lifetime of refresh tokens (default: 2 592 000 = 30 days).
issuer	str | None	Optional iss claim embedded in every token.
audience	list[str] | None	Optional aud claim; validated on every decode.
jwks_enabled	bool	When True, expose a /.well-known/jwks.json endpoint and rotate RSA keys automatically.
key_rotation_interval	int | None	Seconds between automatic RSA key rotations when jwks_enabled=True. None disables auto-rotation.
private_key	str | None	PEM-encoded RSA private key (required for RS256/RS512).
public_key	str | None	PEM-encoded RSA public key (required for RS256/RS512).

---

fastauth.config.PasswordConfig dataclass

Password strength and security settings.

Attributes:

Name	Type	Description
min_length	int	Minimum password length (default: 8).
require_uppercase	bool	Require at least one uppercase letter.
require_lowercase	bool	Require at least one lowercase letter.
require_digit	bool	Require at least one digit.
require_special	bool	Require at least one special character.
max_length	int	Maximum password length (default: 128).

---

fastauth.config.SecurityConfig dataclass

Security settings including account lockout.

Attributes:

Name	Type	Description
max_login_attempts	int	Maximum failed login attempts before lockout (default: 5).
lockout_duration	int	Duration of lockout in seconds (default: 300 = 5 minutes).
login_attempts_by_ip	bool	Also track failed credential login attempts by client IP when the request IP is available. Email-based throttling is always applied.
use_memory_login_attempts_without_token_adapter	bool	Enable provider-local in-memory failed-login tracking when no token_adapter is configured. This fallback is intended only for tests, demos, and single-process development; configure a token_adapter for production so login-attempt state is shared and durable.

---