Package overview¶

The litestar_auth package re-exports the core plugin surface for application code: LitestarAuth, LitestarAuthConfig, plugin config dataclasses, BaseUserManager, UserManagerSecurity, authentication backends/transports, guards, user protocols, ErrorCode, and LitestarAuthError. Controllers, strategies, token stores, rate limiters, payloads, schemas, ORM models, OAuth helpers, and TOTP helpers are imported from their dedicated submodules. ORM models (User, Role, UserRole, OAuthAccount) and the SQLAlchemy adapter (SQLAlchemyUserDatabase) are not re-exported from the root. Import them from the models package or submodules to keep imports explicit and avoid accidental mapper registration:

from litestar_auth.models import User
from litestar_auth.models.oauth import OAuthAccount
from litestar_auth.models.role import Role, UserRole
from litestar_auth.db.sqlalchemy import SQLAlchemyUserDatabase

For the detailed ORM integration contract, use Configuration and the Custom user + OAuth cookbook. This page only names the stable import boundaries. Import Role / UserRole from litestar_auth.models.role when you need the bundled relational role tables without registering the reference User mapper. Import reusable auth-model mixins from litestar_auth.models.mixins.

For the bundled AccessToken / RefreshToken ORM tables, keep explicit mapper registration under the models package:

from litestar_auth.models import import_token_orm_models

AccessToken, RefreshToken, RefreshTokenConsumedDigest = import_token_orm_models()

Call that helper explicitly during metadata bootstrap or Alembic-style autogenerate when your app uses the bundled token tables, including the refresh_token_consumed_digest lookup table. For plugin-managed runtime, LitestarAuth.on_app_init() bootstraps the same bundled token mappers lazily when bundled DB-token models are active. The helper is intentionally not re-exported from litestar_auth.

The DB-token preset entrypoint is exported from both the root package and litestar_auth.plugin as DatabaseTokenAuthConfig. The root package also exports DEFAULT_SUPERUSER_ROLE_NAME for applications that want to reference the built-in "superuser" role while configuring LitestarAuthConfig.superuser_role_name.

For OAuth, plugin-managed apps should configure OAuthConfig on LitestarAuthConfig with oauth_providers as a sequence of OAuthProviderConfig(name=..., client=...). litestar_auth.oauth.create_provider_oauth_controller plus litestar_auth.controllers.create_oauth_controller / create_oauth_associate_controller remain the manual route-table path for custom layouts. The removed litestar_auth.contrib.oauth shim is not part of the public import boundary.

Opaque DB-token wiring:

import os
from uuid import UUID

from litestar import Litestar

from litestar_auth import (
    DatabaseTokenAuthConfig,
    LitestarAuth,
    LitestarAuthConfig,
)
from litestar_auth.manager import UserManagerSecurity
from litestar_auth.models import User

database_token_hash_secret = os.environ["LITESTAR_AUTH_DATABASE_TOKEN_HASH_SECRET"]
reset_password_token_secret = os.environ["LITESTAR_AUTH_RESET_PASSWORD_TOKEN_SECRET"]
verify_token_secret = os.environ["LITESTAR_AUTH_VERIFY_TOKEN_SECRET"]

config = LitestarAuthConfig[User, UUID](
    database_token_auth=DatabaseTokenAuthConfig(
        token_hash_secret=database_token_hash_secret,
    ),
    user_model=User,
    user_manager_class=YourUserManager,
    session_maker=session_maker,
    user_manager_security=UserManagerSecurity(
        verification_token_secret=verify_token_secret,
        reset_password_token_secret=reset_password_token_secret,
    ),
)
app = Litestar(plugins=[LitestarAuth(config)])

In that example, session_maker is any compatible request-session factory callable (session_maker() -> AsyncSession). async_sessionmaker(...) is a common implementation, but not a requirement.

If you previously built the DB bearer backend by hand with AuthenticationBackend(..., BearerTransport(), DatabaseTokenStrategy(...)), migrate to the direct database_token_auth=DatabaseTokenAuthConfig(...) form above. Keep manual backends for multi-backend or custom-transport cases.

backends remains the explicit manual-backend field, and config.resolve_backends(session) is the runtime accessor for every supported backend configuration. For the database_token_auth=... path, config.resolve_startup_backends() returns startup-only StartupBackendTemplate values used during plugin assembly, while config.resolve_backends(session) returns the request-scoped runtime AuthenticationBackend instances.

For app-owned protected routes, reuse config.resolve_openapi_security_requirements() with Litestar guards=[is_authenticated] instead of hard-coding backend names in route-level OpenAPI metadata.

Treat the startup templates as plugin-assembly inventory only: they preserve backend names plus transport/strategy metadata for validation and controller wiring, but DB-token runtime work still has to go through resolve_backends(session) so the realized backend carries the active AsyncSession. Controller selection follows the startup inventory order: the primary backend mounts at /auth, later backends mount at /auth/{backend.name}, plugin-owned OAuth login routes use the primary backend, and TOTP uses the primary backend unless totp_backend_name selects another named startup backend.

Relational role storage changes persistence only. Public HTTP payloads, managers, and guard factories still use one normalized flat roles collection. The core plugin-owned auth/users route table does not auto-mount role catalog or user-assignment endpoints; use the opt-in litestar_auth.contrib.role_admin.RoleAdminExtension, the manual contrib controller factory, or the litestar roles CLI for admin operations. The library does not ship permission matrices.

Organization administration is also available through the extension kernel. Use litestar_auth.contrib.organization_admin.OrganizationAdminExtension for plugin-managed organization-admin HTTP routes, or keep using the public manual factories for custom route tables. The extension requires OrganizationConfig(enabled=True, store_factory=...) and an id_parser, and its invitee-facing accept/decline routes are mounted only with include_invitations=True.

Public surface (high level)¶

The authoritative __all__ list is in litestar_auth/__init__.py on your installed version.

Submodules¶

Detailed API pages are split by module — use the navigation Python API section.