Skip to content

Litestar-Users Configuration

litestar_users.config.LitestarUsersConfig dataclass

Bases: Generic[SQLAUserT, SQLAOAuthAccountT]

Configuration class for LitestarUsers.

auth_config instance-attribute 

auth_config

Authentication backend configuration. Use one of JWTAuthConfig, JWTCookieAuthConfig, or a Litestar session backend config such as ServerSideSessionConfig or CookieBackendConfig.

auth_exclude_paths class-attribute instance-attribute 

auth_exclude_paths = field(default_factory=lambda: ['/schema'])

Paths to be excluded from authentication checks.

auto_commit_transactions class-attribute instance-attribute 

auto_commit_transactions = False

Whether to auto_commit transactions. Defaults to False.

secret instance-attribute 

secret

Secret string for securely signing tokens.

Used for password-reset / verification JWTs as well as for JWT auth backends. Must be 16, 24 or 32 characters.

hash_schemes class-attribute instance-attribute 

hash_schemes = field(default_factory=lambda: ['argon2'])

Schemes to use for password encryption.

Defaults to ["argon2"]

user_repository_class instance-attribute 

user_repository_class

A SQLAlchemyAsyncRepository subclass with model_type set to the user model.

user_registration_dto instance-attribute 

user_registration_dto

DTO class user for user registration.

user_read_dto instance-attribute 

user_read_dto

A User model based SQLAlchemy DTO class.

user_update_dto instance-attribute 

user_update_dto

A User model based SQLAlchemy DTO class.

oauth_account_repository_class class-attribute instance-attribute 

oauth_account_repository_class = None

A SQLAlchemyAsyncRepository subclass with model_type set to the OAuth account model.

Required if oauth2_handler_config or oauth2_associate_handler_config is set.

user_auth_identifier class-attribute instance-attribute 

user_auth_identifier = DEFAULT_USER_AUTH_IDENTIFIER

The identifying attribute to use during user authentication. Defaults to 'email'.

Changing this value requires setting authentication_request_schema as well, which would allow login via e.g. username instead.

Notes
  • The attribute must be present on the User database model and must have a unique value.

user_service_class instance-attribute 

user_service_class

A subclass of BaseUserService.

require_verification_on_registration class-attribute instance-attribute 

require_verification_on_registration = True

Whether the registration of a new user requires verification. Defaults to True.

auth_handler_config class-attribute instance-attribute 

auth_handler_config = None

Optional instance of AuthHandlerConfig. If set, registers the route handler(s) on the app.

Notes
  • At least one route handler config must be set.

current_user_handler_config class-attribute instance-attribute 

current_user_handler_config = None

Optional current-user route handler configuration. If set, registers the route handler(s) on the app.

Notes
  • At least one route handler config must be set.

password_reset_handler_config class-attribute instance-attribute 

password_reset_handler_config = None

Optional password reset route handler configuration. If set, registers the route handler(s) on the app.

Notes
  • At least one route handler config must be set.

register_handler_config class-attribute instance-attribute 

register_handler_config = None

Optional registration/signup route handler configuration. If set, registers the route handler(s) on the app.

Notes
  • At least one route handler config must be set.

oauth2_handler_config class-attribute instance-attribute 

oauth2_handler_config = None

Optional OAuth2 route handler configuration. If set, registers the route handler(s) on the app.

Notes
  • At least one route handler config must be set.

oauth2_associate_handler_config class-attribute instance-attribute 

oauth2_associate_handler_config = None

Optional OAuth2 associate route handler configuration. If set, registers the route handler(s) on the app.

Notes
  • At least one route handler config must be set.

role_management_handler_config class-attribute instance-attribute 

role_management_handler_config = None

Optional role management route handler configuration. If set, registers the route handler(s) on the app.

Notes
  • At least one route handler config must be set.

user_management_handler_config class-attribute instance-attribute 

user_management_handler_config = None

Optional user management route handler configuration. If set, registers the route handler(s) on the app.

Notes
  • At least one route handler config must be set.

verification_handler_config class-attribute instance-attribute 

verification_handler_config = None

Optional user verification route handler configuration. If set, registers the route handler(s) on the app.

Notes
  • At least one route handler config must be set.

Authentication backend configs

litestar_users.config.JWTAuthConfig dataclass

Configuration for JWT-based authentication.

Pass an instance as auth_config to LitestarUsersConfig to use stateless JWT bearer-token authentication.

algorithm class-attribute instance-attribute 

algorithm = 'HS256'

JWT signing algorithm. Defaults to 'HS256'.

auth_header class-attribute instance-attribute 

auth_header = 'Authorization'

Request header that carries the token. Defaults to 'Authorization'.

token_expiration class-attribute instance-attribute 

token_expiration = field(default_factory=lambda: timedelta(days=1))

Lifetime of issued tokens. Defaults to 1 day.

litestar_users.config.JWTCookieAuthConfig dataclass

Bases: JWTAuthConfig

Configuration for cookie-based JWT authentication.

Extends JWTAuthConfig with cookie-specific settings. Pass an instance as auth_config to LitestarUsersConfig to store the token in an HttpOnly cookie in addition to the Authorization header.

cookie_key class-attribute instance-attribute 

cookie_key = 'token'

Cookie name used to store the token. Defaults to 'token'.

cookie_path class-attribute instance-attribute 

cookie_path = '/'

Path scope for the cookie. Defaults to '/'.

cookie_secure class-attribute instance-attribute 

cookie_secure = None

Whether the cookie requires HTTPS. None lets Litestar decide.

cookie_samesite class-attribute instance-attribute 

cookie_samesite = 'lax'

SameSite policy for the cookie. Defaults to 'lax'.

cookie_domain class-attribute instance-attribute 

cookie_domain = None

Domain scope for the cookie. Defaults to None (current domain).

Route handler configs

See Route Handler Configurations for the full reference.

Anonymous access

litestar_users.anonymous.AnonymousUser dataclass

Sentinel representing an unauthenticated (anonymous) request.

Route handlers that allow anonymous access can distinguish authenticated from anonymous callers via isinstance(request.user, AnonymousUser) or by checking request.user.id is Empty.

litestar_users.anonymous.no_validation module-attribute 

no_validation = Dependency(skip_validation=True)

Annotated metadata that bypasses msgspec validation for a dependency.

Required when typing current_user as a union that includes AnonymousUser, because msgspec cannot coerce a union of two custom types::

from typing import Annotated
from litestar_users import AnonymousUser, no_validation

async def handler(
    current_user: Annotated[MyUser | AnonymousUser, no_validation],
) -> ...: ...