Skip to content

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']

"jwt" for stateless JWT sessions (default) or "database" for server-side sessions stored in session_backend.
route_prefix str

URL prefix for all FastAuth endpoints (default: "/auth").
session_backend SessionBackend | None

Required when session_strategy is "database". Provide a :class:~fastauth.core.protocols.SessionBackend such as :class:~fastauth.session_backends.redis.RedisSessionBackend.
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

Full callback URL registered with OAuth providers (e.g. "https://example.com/auth/oauth/callback").
token_adapter TokenAdapter | None

Adapter for persisting one-time verification/reset tokens.
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.

fastauth.config.JWTConfig dataclass

JWT signing and validation settings.

All TTL values are in seconds.

Attributes:

Name Type Description
algorithm str

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).