Package overview¶

The litestar_auth package re-exports stable symbols for application code. ORM models (User, OAuthAccount) and the SQLAlchemy adapter (SQLAlchemyUserDatabase) are not re-exported from the root — import them from their own modules to keep imports explicit and avoid accidental mapper registration:

from litestar_auth.models import User, OAuthAccount
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.

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 = import_token_orm_models()

Call that helper explicitly during metadata bootstrap or Alembic-style autogenerate when your app uses the bundled token tables. For plugin-managed runtime, LitestarAuth.on_app_init() bootstraps the same bundled token mappers lazily when bundled DB-token models are active. The strategy-layer import_token_orm_models() re-export remains compatibility-only for existing imports, and the helper is intentionally not re-exported from litestar_auth.

The canonical opaque DB-token entrypoint is also exported from the root package as DatabaseTokenAuthConfig.

For OAuth, treat root-package re-exports as compatibility aliases. The canonical login-helper import is litestar_auth.oauth.create_provider_oauth_controller, while litestar_auth.controllers.create_oauth_controller and create_oauth_associate_controller are the advanced escape hatch for custom route tables.

Canonical opaque DB-token wiring:

from uuid import UUID

from litestar import Litestar

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

config = LitestarAuthConfig[User, UUID].with_database_token_auth(
    database_token_auth=DatabaseTokenAuthConfig(
        token_hash_secret="replace-with-32+-char-db-token-secret",
    ),
    user_model=User,
    user_manager_class=YourUserManager,
    session_maker=session_maker,
    user_manager_kwargs={
        "verification_token_secret": "replace-with-32+-char-secret",
        "reset_password_token_secret": "replace-with-32+-char-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 preset above. Keep manual backends for multi-backend or custom-transport cases.

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.