Models¶

Package litestar_auth.models exposes the reference User, Role, UserRole, OAuthAccount, ApiKey, Organization, and OrganizationMembership ORM models plus the side-effect-free mixins behind the bundled model family. Names are loaded lazily (PEP 562) when accessed on the package.

Import paths¶

Use Configuration as the main ORM setup guide for token bootstrap lifecycle, relational role composition, custom model families, SQLAlchemyUserDatabase, and password-column customization. Use the Custom user + OAuth cookbook when the application owns the user table.

Avoid from litestar_auth.models import User (or the user submodule) in apps that already map table user to a custom model. That import registers the bundled reference mapper and conflicts with an app-owned mapping. Likewise, importing OAuthAccount from litestar_auth.models.oauth only keeps the reference User lazy; when the app owns a different user class, table, or registry, prefer an OAuthAccountMixin subclass that points back at the custom user contract.

import_token_orm_models() remains the explicit helper for bundled token metadata bootstrap and Alembic-style autogenerate. It returns AccessToken, RefreshToken, and RefreshTokenConsumedDigest so the bundled refresh-token consumed-digest lookup table is part of the documented bootstrap surface. LitestarAuth.on_app_init() also calls the same helper lazily for plugin-managed runtime when bundled DB-token models are active, so no extra import side effect is required only to make the plugin work. DatabaseTokenModels defaults to those same three classes at runtime; pass consumed_refresh_token_digest_model=... only when a custom consumed-digest lookup table should back refresh-token replay detection.

For custom SQLAlchemy models, compose the mixins on your own declarative base instead of copying columns or relationship wiring from the reference classes. Configuration covers the full support matrix and migration notes.

refresh_token session metadata¶

The bundled RefreshTokenMixin stores refresh tokens as keyed digests only. It also adds the DB-backed session metadata required by session/device management:

• session_id — a generated UUID string used as the stable public session identifier. It is distinct from token and must be the only refresh-session identifier exposed by API responses.
• created_at — the original refresh session creation timestamp.
• last_used_at — nullable timestamp set when a refresh token is successfully rotated.
• client_metadata — nullable bounded JSON metadata derived from login/refresh requests. The built-in controller stores only a normalized user_agent value capped at 255 characters.

Refresh rotation keeps the same session_id and created_at, atomically replaces only the token digest, records the consumed digest, updates last_used_at, and refreshes client_metadata when request metadata is available. Re-presenting any consumed refresh token is treated as a compromise signal and revokes the entire refresh-session chain. The bundled strategy also stores each consumed digest in refresh_token_consumed_digest, keyed by digest with an index on session_id, so replay checks perform an indexed equality lookup instead of scanning refresh-token rows.

Existing deployments using the bundled refresh_token table must add session_id, last_used_at, and client_metadata columns before using this version. Deployments upgrading to refresh-token reuse detection must also create the refresh_token_consumed_digest lookup table. Backfill session_id with a unique non-sensitive UUID per existing row. If the deployment is upgrading from a version that stored legacy digests in refresh_token.consumed_token_digests, backfill every legacy digest into refresh_token_consumed_digest, then drop the legacy JSON column before serving traffic with the new code. Skipping the lookup-table backfill means refresh tokens consumed before the upgrade and replayed after it are rejected as ordinary missing tokens instead of revoking the compromised session chain until the legacy sessions expire or are explicitly revoked. Existing custom refresh-token models passed through DatabaseTokenModels must expose mapped session_id, last_used_at, and client_metadata attributes; custom consumed-digest models must expose mapped token_digest, session_id, and consumed_at attributes. Otherwise configuration fails fast with ConfigurationError.

api_key shape¶

The bundled ApiKeyMixin stores API-key metadata and verifier material:

• key_id — public lookup id embedded in the raw credential.
• hashed_secret — keyed HMAC digest of the raw bearer secret.
• encrypted_secret — nullable encrypted raw secret for signing-required keys.
• name, scopes, prefix_env, signing_required, expires_at, last_used_at, revoked_at, created_via, and client_metadata — safe management metadata.

Import ApiKey from litestar_auth.models.api_key or lazily from litestar_auth.models. Use ApiKeyMixin on a custom declarative base when the application owns the model family. The SQLAlchemy store lives at litestar_auth.db.sqlalchemy.SQLAlchemyApiKeyStore; the lazy litestar_auth.db package exports only BaseApiKeyStore and ApiKeyData.

Lazy imports and IDE support¶

litestar_auth.models exposes names such as User and OAuthAccount through PEP 562 __getattr__ so that importing the package does not register SQLAlchemy mappers or run other ORM side effects until a symbol is accessed.

Static type checkers still see those symbols with full annotations (the package uses TYPE_CHECKING-friendly patterns for stubs and forward references). Some IDEs cannot resolve go to definition or offer reliable autocomplete through a runtime __getattr__ hook. For full IDE support—jump to definition, rename, and completion—import from the concrete modules directly:

• from litestar_auth.models.user import User
• from litestar_auth.models.oauth import OAuthAccount
• from litestar_auth.models.organization import Organization, OrganizationMembership

The import paths table restates the same guidance in task-oriented form.

UserModelMixin hook¶

UserModelMixin keeps the runtime attribute contract on hashed_password. When an app-owned user table only needs a different SQL column name, set auth_hashed_password_column_name on the custom user class:

class CustomUser(UserModelMixin, UserAuthRelationshipMixin, AppUUIDBase):
    __tablename__ = "custom_user"
    auth_hashed_password_column_name = "password_hash"

BaseUserManager, SQLAlchemyUserDatabase, and JWT password fingerprinting still read and write user.hashed_password; only the SQL column name changes. If an app needs more than a column-name remap, it can still own the mapped attribute directly with hashed_password = mapped_column(...) on the app model.

UserAuthRelationshipMixin hooks¶

UserAuthRelationshipMixin keeps the bundled inverse relationship contract by default: back_populates="user" on access_tokens, refresh_tokens, and oauth_accounts, with SQLAlchemy's normal loader behavior and inferred foreign-key linkage. Override only the narrow class hooks the mixin documents:

• auth_access_token_model, auth_refresh_token_model, auth_oauth_account_model point those inverse relationships at custom mapped classes, or to None when a branch is intentionally omitted.
• auth_token_relationship_lazy forwards one optional lazy= setting to both token collections.
• auth_oauth_account_relationship_lazy forwards one optional lazy= setting to oauth_accounts.
• auth_oauth_account_relationship_foreign_keys forwards one optional foreign_keys= hint to oauth_accounts.

The mixin does not accept arbitrary relationship() kwargs. For behavior outside those hooks, keep an app-owned explicit relationship definition.

Relational role hooks¶

UserRoleRelationshipMixin is the supported user-side role facade. It keeps user.roles -> list[str] as the normalized public contract while persisting membership through relationship rows instead of a JSON column on the user table.

• auth_user_role_model points role_assignments at the association-row mapper.
• auth_user_role_relationship_lazy forwards one optional lazy= setting to role_assignments.

RoleMixin and UserRoleAssociationMixin provide the sibling tables behind that facade:

• RoleMixin maps the global role catalog row (name) plus inverse user_assignments.
• UserRoleAssociationMixin maps the (user_id, role_name) association row and the user / role relationships.
• The association mixin hooks (auth_user_model, auth_user_table, auth_role_model, auth_role_table) let apps point the same boilerplate at custom table names and mapped classes.

The bundled User model composes UserRoleRelationshipMixin, and the bundled Role / UserRole models are the reference implementation of the same contract.

Role shape¶

The bundled relational role family consists of:

• role.name — normalized global role name, primary key
• user_role.user_id — foreign key to user.id, part of the composite primary key
• user_role.role_name — foreign key to role.name, part of the composite primary key

At the library boundary, the user contract is still the normalized flat roles: list[str] surface consumed by managers, schemas, and guards. The relational tables are an internal persistence detail of the bundled/custom SQLAlchemy model family, not a change to the higher-level role API.

Migrating from legacy JSON roles¶

If an existing deployment still stores roles in a JSON column on the user row, migrate in this order:

1. Create role and user_role, or the equivalent custom tables built from RoleMixin / UserRoleAssociationMixin.
2. Normalize and deduplicate each stored role array with the same trim/lowercase rules used by the library.
3. Backfill one role row per normalized name and one user_role row per (user, role) pair.
4. Switch the app to the bundled Role / UserRole models or a custom mixin-composed role family.
5. Remove or ignore the legacy JSON column once reads and writes use relational membership.

Relational role storage does not change the higher-level auth contract: managers, schemas, and guards still operate on flat normalized roles, and the library does not provide RBAC permission matrices or policy DSLs.

Organization shape¶

The bundled organization family consists of:

• organization.id — UUID primary key
• organization.slug — normalized unique tenant slug, indexed
• organization.name — display name
• organization.created_at / organization.updated_at — server-managed audit timestamps
• organization_membership.user_id — foreign key to user.id, part of the composite primary key
• organization_membership.organization_id — foreign key to organization.id, part of the composite primary key
• organization_membership.roles — normalized JSON list of organization-scoped role names
• Unique constraint on (user_id, organization_id)

Import the reference models lazily from litestar_auth.models or directly from litestar_auth.models.organization:

from litestar_auth.models import Organization, OrganizationMembership

OrganizationMixin and OrganizationMembershipMixin are side-effect-free composition helpers for custom declarative bases. The membership mixin reuses the same configurable user foreign-key contract as other user-owned auth rows and adds configurable organization-table hooks.

Organization models are intentionally not exported from litestar_auth or litestar_auth.db. litestar_auth.db exports only BaseOrganizationStore, OrganizationData, and MembershipData; the SQLAlchemy adapter lives at litestar_auth.db.sqlalchemy.SQLAlchemyOrganizationStore.

Phase-1 organization persistence does not alter authorization behavior. There are no organization-scoped guards, tenant-resolution middleware, JWT org_id claim, organization admin routes, or automatic filters for application-owned tables.

oauth_account shape¶

The library table (bundled OAuthAccount) includes at least:

• id — UUID primary key (from UUIDBase)
• user_id — FK to user.id, not null
• oauth_name — String(100)
• account_id — String(255)
• account_email — String(320)
• access_token — EncryptedString-backed (length 4096), Fernet when a key is configured
• expires_at — integer epoch or null
• refresh_token — optional, same encryption type as access token
• Unique constraint uq_oauth_account_provider_identity on (oauth_name, account_id)

Token encryption uses litestar_auth.oauth_encryption and OAuthConfig.oauth_token_encryption_keyring or the one-key oauth_token_encryption_key shortcut (see OAuth guide).

For audit columns (created_at / updated_at), use one mapped class per table; see OAuth guide — audit columns.

55
56
57
58
59
60
61

def __init_subclass__(cls, **kwargs: object) -> None:
    """Register OAuth token encryption hooks when an OAuth model family is declared."""
    super().__init_subclass__(**kwargs)
    if _inherits_registered_oauth_hooks(cls):
        return
    register_oauth_model_encryption_events(cls)
    setattr(cls, _OAUTH_EVENTS_REGISTERED_ATTR, True)

63
64
65
66
67
68
69
70
71
72
73
74

@declared_attr.directive
@classmethod
def __table_args__(cls) -> tuple[UniqueConstraint]:  # noqa: PLW3201
    """Create the provider-identity uniqueness constraint for each subclass.

    Returns:
        The unique constraint tuple for ``(oauth_name, account_id)``.
    """
    constraint_name = cls.auth_provider_identity_constraint_name
    if constraint_name is None:
        constraint_name = f"uq_{cls.__tablename__}_provider_identity"
    return (UniqueConstraint("oauth_name", "account_id", name=constraint_name),)

505
506
507
508
509
510
511
512
513
514
515
516

@declared_attr
@classmethod
def organization(cls) -> Mapped[Any]:
    """Map the relationship back to the configured organization model.

    Returns:
        The relationship descriptor for the configured organization model.
    """
    relationship_kwargs: dict[str, Any] = {"back_populates": cls.auth_organization_back_populates}
    if cls.auth_organization_relationship_foreign_keys:
        relationship_kwargs["foreign_keys"] = lambda: [cast("Mapped[Any]", cls.organization_id)]
    return relationship(cls.auth_organization_model, **relationship_kwargs)

491
492
493
494
495
496
497
498
499
500
501
502
503

@declared_attr
@classmethod
def organization_id(cls) -> Mapped[uuid.UUID]:
    """Map the organization foreign key for the invitation row.

    Returns:
        The mapped organization foreign-key column.
    """
    return mapped_column(
        ForeignKey(f"{cls.auth_organization_table}.id", ondelete=cls.auth_organization_id_ondelete),
        index=True,
        nullable=False,
    )

441
442
443
444
445
446
447
448
449
450
451
452

@declared_attr
@classmethod
def organization(cls) -> Mapped[Any]:
    """Map the relationship back to the configured organization model.

    Returns:
        The relationship descriptor for the configured organization model.
    """
    relationship_kwargs: dict[str, Any] = {"back_populates": cls.auth_organization_back_populates}
    if cls.auth_organization_relationship_foreign_keys:
        relationship_kwargs["foreign_keys"] = lambda: [cast("Mapped[Any]", cls.organization_id)]
    return relationship(cls.auth_organization_model, **relationship_kwargs)

428
429
430
431
432
433
434
435
436
437
438
439

@declared_attr
@classmethod
def organization_id(cls) -> Mapped[uuid.UUID]:
    """Map the organization foreign key for the membership row.

    Returns:
        The mapped organization foreign-key column.
    """
    return mapped_column(
        ForeignKey(f"{cls.auth_organization_table}.id", ondelete=cls.auth_organization_id_ondelete),
        primary_key=True,
    )

235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252

@declared_attr
@classmethod
def invitations(cls) -> Mapped[list[Any]]:
    """Map the inverse collection of organization-invitation rows.

    Returns:
        The relationship descriptor for organization-invitation rows.
    """
    if cls.auth_organization_invitation_model is None:
        return cast("Mapped[list[Any]]", None)

    relationship_kwargs: dict[str, Any] = {
        "back_populates": "organization",
        "cascade": "all, delete-orphan",
    }
    if cls.auth_organization_invitation_relationship_lazy is not None:
        relationship_kwargs["lazy"] = cls.auth_organization_invitation_relationship_lazy
    return relationship(cls.auth_organization_invitation_model, **relationship_kwargs)

219
220
221
222
223
224
225
226
227
228
229
230
231
232
233

@declared_attr
@classmethod
def memberships(cls) -> Mapped[list[Any]]:
    """Map the inverse collection of organization-membership rows.

    Returns:
        The relationship descriptor for organization-membership rows.
    """
    relationship_kwargs: dict[str, Any] = {
        "back_populates": "organization",
        "cascade": "all, delete-orphan",
    }
    if cls.auth_organization_membership_relationship_lazy is not None:
        relationship_kwargs["lazy"] = cls.auth_organization_membership_relationship_lazy
    return relationship(cls.auth_organization_membership_model, **relationship_kwargs)

174
175
176
177
178
179
180
181
182
183
184
185
186
187
188

@declared_attr
@classmethod
def user_assignments(cls) -> Mapped[list[Any]]:
    """Map the inverse collection of user-role association rows.

    Returns:
        The relationship descriptor for user-role association rows.
    """
    relationship_kwargs: dict[str, Any] = {
        "back_populates": "role",
        "cascade": "all, delete-orphan",
    }
    if cls.auth_user_role_relationship_lazy is not None:
        relationship_kwargs["lazy"] = cls.auth_user_role_relationship_lazy
    return relationship(cls.auth_user_role_model, **relationship_kwargs)

652
653
654
655
656
657
658
659
660
661
662
663

@declared_attr
@classmethod
def access_tokens(cls) -> Mapped[list[Any]]:
    """Map the inverse side of the configured access-token model when enabled.

    Returns:
        The relationship descriptor, or ``None`` when access-token integration is disabled.
    """
    return cls._relationship(
        cls.auth_access_token_model,
        lazy=cls.auth_token_relationship_lazy,
    )

678
679
680
681
682
683
684
685
686
687
688
689

@declared_attr
@classmethod
def api_keys(cls) -> Mapped[list[Any]]:
    """Map the inverse side of the configured API-key model when enabled.

    Returns:
        The relationship descriptor, or ``None`` when API-key integration is disabled.
    """
    return cls._relationship(
        cls.auth_api_key_model,
        lazy=cls.auth_token_relationship_lazy,
    )

691
692
693
694
695
696
697
698
699
700
701
702
703

@declared_attr
@classmethod
def oauth_accounts(cls) -> Mapped[list[Any]]:
    """Map the inverse side of the configured OAuth-account model when enabled.

    Returns:
        The relationship descriptor, or ``None`` when OAuth-account integration is disabled.
    """
    return cls._relationship(
        cls.auth_oauth_account_model,
        lazy=cls.auth_oauth_account_relationship_lazy,
        foreign_keys=cls.auth_oauth_account_relationship_foreign_keys,
    )

705
706
707
708
709
710
711
712
713
714
715
716

@declared_attr
@classmethod
def organization_memberships(cls) -> Mapped[list[Any]]:
    """Map the inverse side of the configured organization-membership model when enabled.

    Returns:
        The relationship descriptor, or ``None`` when organization integration is disabled.
    """
    return cls._relationship(
        cls.auth_organization_membership_model,
        lazy=cls.auth_organization_membership_relationship_lazy,
    )

665
666
667
668
669
670
671
672
673
674
675
676

@declared_attr
@classmethod
def refresh_tokens(cls) -> Mapped[list[Any]]:
    """Map the inverse side of the configured refresh-token model when enabled.

    Returns:
        The relationship descriptor, or ``None`` when refresh-token integration is disabled.
    """
    return cls._relationship(
        cls.auth_refresh_token_model,
        lazy=cls.auth_token_relationship_lazy,
    )

 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103

@declared_attr
@classmethod
def hashed_password(cls) -> Mapped[str]:
    """Map the password-hash attribute to the configured SQL column name.

    Returns:
        The mapped ``hashed_password`` column.
    """
    column_name = cls.auth_hashed_password_column_name
    if column_name == "hashed_password":
        return mapped_column(String(length=255))
    return mapped_column(column_name, String(length=255))

396
397
398
399
400
401
402
403
404
405
406
407
408

@declared_attr
@classmethod
def role(cls) -> Mapped[Any]:
    """Map the relationship back to the configured role model.

    Returns:
        The relationship descriptor for the configured role model.
    """
    return relationship(
        cls.auth_role_model,
        back_populates=cls.auth_role_back_populates,
        foreign_keys=lambda: [cast("Mapped[Any]", cls.role_name)],
    )

373
374
375
376
377
378
379
380
381
382
383
384
385

@declared_attr
@classmethod
def role_name(cls) -> Mapped[str]:
    """Map the normalized role-name foreign key for the association row.

    Returns:
        The mapped role-name foreign-key column.
    """
    return mapped_column(
        String(length=_ROLE_NAME_LENGTH),
        ForeignKey(f"{cls.auth_role_table}.name"),
        primary_key=True,
    )

120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

@declared_attr
@classmethod
def role_assignments(cls) -> Mapped[list[Any]]:
    """Map the user-side role-assignment collection.

    Returns:
        The relationship descriptor for role-assignment rows.
    """
    relationship_kwargs: dict[str, Any] = {
        "back_populates": _USER_RELATIONSHIP_NAME,
        "cascade": "all, delete-orphan",
        "passive_deletes": True,
    }
    if cls.auth_user_role_relationship_lazy:
        relationship_kwargs["lazy"] = cls.auth_user_role_relationship_lazy
    return relationship(cls.auth_user_role_model, **relationship_kwargs)

109
110
111

def __dir__() -> list[str]:
    """Return public model names for discovery."""
    return sorted(__all__)

 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106

def __getattr__(name: str) -> object:
    """Load lazy model exports on demand.

    Returns:
        The requested ORM model or mixin.

    Raises:
        AttributeError: If ``name`` is not a public export.
    """
    module_name = {
        "AccessTokenMixin": "litestar_auth.models.mixins",
        "ApiKey": "litestar_auth.models.api_key",
        "ApiKeyMixin": "litestar_auth.models.mixins",
        "OAuthAccount": "litestar_auth.models.oauth",
        "OAuthAccountMixin": "litestar_auth.models.mixins",
        "Organization": "litestar_auth.models.organization",
        "OrganizationInvitation": "litestar_auth.models.organization",
        "OrganizationInvitationMixin": "litestar_auth.models.mixins",
        "OrganizationMembership": "litestar_auth.models.organization",
        "OrganizationMembershipMixin": "litestar_auth.models.mixins",
        "OrganizationMixin": "litestar_auth.models.mixins",
        "RefreshTokenMixin": "litestar_auth.models.mixins",
        "Role": "litestar_auth.models.role",
        "RoleMixin": "litestar_auth.models.mixins",
        "User": "litestar_auth.models.user",
        "UserAuthRelationshipMixin": "litestar_auth.models.mixins",
        "UserModelMixin": "litestar_auth.models.mixins",
        "UserRole": "litestar_auth.models.role",
        "UserRoleAssociationMixin": "litestar_auth.models.mixins",
        "UserRoleRelationshipMixin": "litestar_auth.models.mixins",
    }.get(name)
    if module_name is None:
        msg = f"module {__name__!r} has no attribute {name!r}"
        raise AttributeError(msg)
    return getattr(import_module(module_name), name)

14
15
16
17
18
19
20
21
22
23
24
25

def import_token_orm_models() -> tuple[type[AccessToken], type[RefreshToken], type[RefreshTokenConsumedDigest]]:
    """Return all bundled token ORM models for explicit and plugin-owned bootstrap.

    This remains the public helper for metadata bootstrap and Alembic-style
    autogenerate flows. ``LitestarAuth.on_app_init()`` also calls it lazily when bundled
    DB-token models are active, so plugin-managed runtime no longer depends on a separate
    app-level import side effect. The helper keeps token-model discovery under
    ``litestar_auth.models`` without importing the reference ``User`` mapper.
    """
    db_models_module = importlib.import_module("litestar_auth.authentication.strategy.db_models")

    return db_models_module.import_token_orm_models()