Payloads and Schemas¶
litestar_auth.payloads is the authoritative public boundary for the built-in auth lifecycle DTOs published by the
default controllers. litestar_auth.schemas still documents the default user CRUD structs used for registration and
user-facing reads or updates.
UserEmailField and UserPasswordField are the supported public schema-helper aliases for app-owned
msgspec.Struct registration, admin update, or password-rotation schemas. Import them from litestar_auth.schemas
when you want custom email and password fields to keep the same documented regex, max-length, and
password-length metadata as the built-in credential-bearing structs without copying local constraints.
UserUpdate intentionally excludes password; self-service password rotation uses ChangePasswordRequest.
Existing UserPasswordField imports remain supported; add UserEmailField when you also want the built-in email
contract on app-owned schemas. For the full contract between schema metadata, password_validator_factory, and
shared PasswordHelper injection, see
Configuration.
These aliases only describe schema validation and OpenAPI metadata. Runtime password policy still lives on the
manager side through password_validator_factory or the manager's default validator.
Schema usage example:
import msgspec
from litestar_auth.schemas import UserEmailField, UserPasswordField
class AppUserCreate(msgspec.Struct, forbid_unknown_fields=True):
email: UserEmailField
password: UserPasswordField
Built-in auth payloads¶
Import path
Prefer importing built-in request and response structs from litestar_auth.payloads:
The package root (litestar_auth) and controllers package (litestar_auth.controllers) no longer re-export
these types. User CRUD schemas also stay in litestar_auth.schemas instead of passing through this module.
Import auth lifecycle DTOs from litestar_auth.payloads so code follows the documented payload boundary.
Use these types when you want the exact request and response structs exposed by the built-in login, refresh, session/device management, verify, reset-password, TOTP, and API-key routes.
litestar_auth.payloads
¶
Public msgspec payloads for built-in auth and user flows.
The supported import path for these structs is litestar_auth.payloads.
Payload structs are intentionally not re-exported from litestar_auth; import
them from this module so imports stay explicit for readers and tooling.
LoginCredentials
¶
Bases: Struct
Login payload accepted by the auth controller.
RefreshTokenRequest
¶
Bases: Struct
Refresh payload accepted by the auth controller.
RefreshSessionRead
¶
Bases: Struct
Safe refresh-session representation returned by session/device APIs.
The public session_id is intentionally distinct from stored token
digests and raw refresh tokens. client_metadata is limited to bounded,
non-secret client hints such as the normalized user_agent value stored
by the database token strategy.
RefreshSessionListResponse
¶
Bases: Struct
Response returned when listing active refresh sessions for a user.
ApiKeyAdminCreateRequest
¶
Bases: Struct
Payload used by superusers to create an API key for a path-selected user.
ApiKeyCreateRequest
¶
Bases: Struct
Payload used to create a user-owned API key.
ApiKeyCreateResponse
¶
Bases: Struct
Creation response containing the one-time raw API key.
ApiKeyUpdateRequest
¶
Bases: Struct
Payload used to update mutable API-key metadata.
ApiKeyRead
¶
Bases: Struct
Safe API-key metadata returned by API-key management endpoints.
ApiKeyListResponse
¶
Bases: Struct
Response returned when listing API keys.
ForgotPassword
¶
Bases: Struct
Payload used to request a reset-password token.
ResetPassword
¶
Bases: Struct
Payload used to reset a password with a previously issued token.
RequestVerifyToken
¶
Bases: Struct
Payload used to request a fresh email-verification token.
VerifyToken
¶
Bases: Struct
Payload used to complete an email-verification flow.
TotpEnableRequest
¶
Bases: Struct
Optional step-up payload for enabling 2FA.
TotpEnableResponse
¶
Bases: Struct
Response returned when 2FA enrollment is initiated (phase 1).
The secret is not yet persisted. The client must confirm enrollment via
/enable/confirm with a valid TOTP code to activate 2FA.
TotpVerifyRequest
¶
Bases: Struct
Payload for completing 2FA login verification.
code accepts either a current TOTP code or an unused recovery code.
TotpConfirmEnableRequest
¶
Bases: Struct
Payload for confirming TOTP enrollment (phase 2).
TotpConfirmEnableResponse
¶
Bases: Struct
Response returned when 2FA is successfully confirmed and persisted.
Recovery codes are returned only in this response and should be shown once. The library persists only hashed recovery-code values.
TotpRegenerateRecoveryCodesRequest
¶
Bases: Struct
Step-up payload for rotating TOTP recovery codes.
Required only when totp_enable_requires_password=True. When that
policy is disabled, the regenerate route accepts no request body.
TotpRecoveryCodesResponse
¶
Bases: Struct
Response containing one-time plaintext TOTP recovery codes.
The values are returned only from confirm-enable or regenerate responses. Storage keeps only hashed values in the user model.
TotpDisableRequest
¶
Bases: Struct
Payload for disabling 2FA.
code accepts either a current TOTP code or an unused recovery code.
User CRUD schemas¶
These remain the default msgspec schemas for registration, user CRUD, and self-service password rotation surfaces.
Import UserCreate, UserRead, UserUpdate, AdminUserUpdate, and ChangePasswordRequest from
litestar_auth.schemas; neither the package root nor litestar_auth.payloads re-exports them.
UserEmailField and UserPasswordField live here as well and are the supported aliases for sharing the built-in
email/password metadata with app-owned credential-bearing structs while the manager keeps runtime validation for
passwords.
litestar_auth.schemas
¶
Public msgspec schemas and schema helpers for litestar-auth user payloads.
Import UserEmailField and UserPasswordField from this module when
app-owned msgspec.Struct user create, self-update, admin update, or
change-password schemas should share the same email and password metadata as
the built-in payloads. Self-service UserUpdate accepts
current_password only as a step-up credential for email changes; use the
dedicated ChangePasswordRequest contract for authenticated password
rotation.
AdminUserUpdate
¶
Bases: Struct
Privileged admin update payload.
Admin writes may include password for operator-initiated credential
rotation. current_password and totp_code are step-up proof for the
authenticated admin and are not forwarded to persistence. This schema is
used for PATCH /users/{user_id}, not for self-service PATCH
/users/me requests.
ChangePasswordRequest
¶
Bases: Struct
Self-service password-rotation payload.
POST /users/me/change-password requires the current password plus the
replacement password. The controller re-verifies the current credential
before delegating the new password to the manager update lifecycle.
UserCreate
¶
Bases: Struct
Payload used to create a new user.
UserRead
¶
Bases: Struct
Public user representation returned by the API.
UserUpdate
¶
Bases: Struct
Self-service profile-update payload (non-privileged).
Security
Privileged fields (is_active, is_verified, roles) are not
accepted on this self-service contract. They belong to
:class:AdminUserUpdate via privileged PATCH /users/{user_id}
instead. Email changes require current_password so the authenticated
session re-proves the user's password before identity mutation.
Password rotation goes through :class:ChangePasswordRequest on
POST /users/me/change-password so the current password can be
re-verified first. forbid_unknown_fields=True rejects any of those
fields at decode time, so the persistence layer's defense-in-depth
deny-list never has to run on an incoming self-service body.