Bases: ABC, Generic[UserType, AuthType]

A base class for Security Configs - this class can be used on the application level or be manually configured on the router / controller level to provide auth.

authentication_middleware_class: type[AbstractAuthenticationMiddleware]#

The authentication middleware class to use.

Must inherit from AbstractAuthenticationMiddleware

guards: Iterable[Guard] | None = None#

An iterable of guards to call for requests, providing authorization functionalities.

exclude: str | list[str] | None = None#

A pattern or list of patterns to skip in the authentication middleware.

exclude_opt_key: str = 'exclude_from_auth'#

An identifier to use on routes to disable authentication and authorization checks for a particular route.

exclude_http_methods: Sequence[Method] | None = Field(name=None,type=None,default=<dataclasses._MISSING_TYPE object>,default_factory=<function AbstractSecurityConfig.<lambda>>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=<dataclasses._MISSING_TYPE object>,_field_type=None)#

A sequence of http methods that do not require authentication. Defaults to [‘OPTIONS’, ‘HEAD’]

scopes: Scopes | None = None#

ASGI scopes processed by the authentication middleware, if None, both http and websocket will be processed.

route_handlers: Iterable[ControllerRouterHandler] | None = None#

An optional iterable of route handlers to register.

dependencies: dict[str, Provide] | None = None#

An optional dictionary of dependency providers.

retrieve_user_handler: Callable[[Any, ASGIConnection], SyncOrAsyncUnion[Any | None]]#

Callable that receives the auth value from the authentication middleware and returns a user value.


  • User and Auth can be any arbitrary values specified by the security backend.

  • The User and Auth values will be set by the middleware as scope["user"] and scope["auth"] respectively. Once provided, they can access via the connection.user and connection.auth properties.

  • The callable can be sync or async. If it is sync, it will be wrapped to support async.

type_encoders: TypeEncodersMap | None = None#

A mapping of types to callables that transform them into types supported for serialization.

on_app_init(app_config: AppConfig) AppConfig#

Handle app init by injecting middleware, guards etc. into the app. This method can be used only on the app level.


app_config – An instance of AppConfig


The AppConfig.

create_response(content: Any | None, status_code: int, media_type: MediaType | OpenAPIMediaType | str, headers: dict[str, Any] | None = None, cookies: ResponseCookies | None = None) Response[Any]#

Create a response object.

Handles setting the type encoders mapping on the response.

  • content – A value for the response body that will be rendered into bytes string.

  • status_code – An HTTP status code.

  • media_type – A value for the response ‘Content-Type’ header.

  • headers – A string keyed dictionary of response headers. Header keys are insensitive.

  • cookies – A list of Cookie instances to be set under the response ‘Set-Cookie’ header.


A response object.

abstract property openapi_components: Components#

Create OpenAPI documentation for the JWT auth schema used.


An Components instance.

abstract property security_requirement: SecurityRequirement#

Return OpenAPI 3.1.

SecurityRequirement for the auth backend.


An OpenAPI 3.1 SecurityRequirement dictionary.

abstract property middleware: DefineMiddleware#

Create an instance of the config’s authentication_middleware_class attribute and any required kwargs, wrapping it in Litestar’s DefineMiddleware.


An instance of DefineMiddleware.