Adapters¶
Adapters are the persistence layer. They implement the protocols in fastauth.core.protocols; FastAuth never imports a specific ORM.
Sub-adapters¶
| Adapter | Config field | Required for |
|---|---|---|
UserAdapter |
adapter (in FastAuthConfig) |
Everything. Reads/writes users, password hashes. |
TokenAdapter |
token_adapter |
Refresh tokens (default), email verification, password reset, email change, magic links, credentials lockout tracking. |
SessionAdapter |
auth.session_adapter (post-construction) |
/auth/sessions endpoints (list/revoke). Independent of session_strategy. |
RoleAdapter |
auth.role_adapter (post-construction) |
RBAC: /auth/roles/*, require_role, require_permission. |
OAuthAccountAdapter |
oauth_adapter (in FastAuthConfig) |
All OAuth endpoints. |
PasskeyAdapter |
passkey_adapter (in FastAuthConfig) |
All passkey endpoints. |
SessionAdapter≠SessionBackend.SessionAdapterpersists server-side session rows (used by/auth/sessions).SessionBackend(read/write/delete/exists) stores short-lived state for OAuth PKCE/state and WebAuthn challenges. They are different protocols used by different parts of FastAuth.
Which adapter goes where¶
| Object | Set in FastAuthConfig(...) |
Set post-construction |
|---|---|---|
adapter (UserAdapter) |
yes | — |
token_adapter |
yes | — |
oauth_adapter |
yes | — |
passkey_adapter |
yes | — |
oauth_state_store, passkey_state_store |
yes (SessionBackend) | — |
role_adapter |
— | auth.role_adapter = adapter.role |
session_adapter |
— | auth.session_adapter = adapter.session |
Built-in adapters¶
- SQLAlchemy — SQLite, PostgreSQL, MySQL. Single umbrella
SQLAlchemyAdapterexposes every sub-adapter. - Memory — six in-memory sub-adapters for tests and local demos. Not for production.
- Custom — implement the protocols for your own ORM.
Email identity¶
Emails are normalized (lowercased and stripped) via fastauth.core.identity.normalize_email before any adapter lookup. Your UserAdapter.create_user and get_user_by_email are responsible for consistently storing and querying the normalized form. The SQLAlchemy adapter normalizes for you; if you build a custom adapter, do not skip normalization or duplicate-email bugs will appear.