Migrating to 0.15
0.15 completes the typed server API and tightens existing account, storage, session, and plugin contracts. It does not add OAuth/OIDC, MFA, passkeys, or a hosted identity service. Back up production data and test the upgrade on a copy before deploying.
Upgrade order
- Read the storage migration guide, sessions/JWKS guide, and typed SDK/plugin guide. Custom adapters and session strategies need changes; startup now fails closed when required atomic capabilities are missing. There is no unsafe read/modify/write fallback.
- Update dependencies and application lockfiles. Install
fastauth-py==0.15.0with the same extras you use today. Python 3.11β3.13 are supported (>=3.11,<3.14); applications on Python 3.14 must first move to a supported interpreter and rebuild their environment. - Stop all 0.14 workers before applying database migrations. Mixed-version
refresh writers are unsupported. For existing Mongo databases, run the
explicit offline
migrate_mongo_storage_v015step in the storage guide before normal CLI initialization; startup deliberately will not drop legacy indexes. For Postgres, run the normal tracked CLI migration workflow. - Plan a refresh-token reauthentication event. Old Postgres refresh credentials are deleted by the tracked migration; old Mongo refresh rows without family coordination state are rejected. Users sign in again to obtain new refresh credentials. Existing access sessions retain their normal expiration and remain subject to account policy.
- Start 0.15 with checked migrations, run readiness checks, and exercise signup, verification, sign-in, refresh, logout, and password recovery against your actual database. Database test jobs must execute, not silently skip.
Downgrading Python packages does not reverse database changes. Keep a tested backup and rollback plan. Never restart old workers against active 0.15 Mongo refresh-family state. The linked storage/session guides describe cleanup, index changes, custom-adapter obligations, and retained family tombstones.
Dependency and Python serialization contract
Python support is narrowed to >=3.11,<3.14 for core and every extra. The 0.14
Python 3.14 support claim cannot be retained because current Beanie 2.x releases
explicitly exclude that interpreter. Version 0.15 keeps one tested support range
across all first-party adapters rather than skipping an incompatible database
job or pinning an older Beanie release to bypass its current compatibility
limit. Recreate Python 3.14 environments on Python 3.11, 3.12, or 3.13 before
upgrading. Do not use resolver options that ignore Requires-Python metadata.
Pydantic now requires >=2.11,<3. serialize_by_alias was introduced in
Pydantic 2.11.
Previously allowed Pydantic 2.8 installations ignored that setting, so the same
UserView.model_dump() could emit snake_case instead of camelCase. Supported
installs now emit public response aliases consistently. Requesting
model_dump(by_alias=False) still gives Python field names explicitly.
The JWT extra now requires joserfc >=1.5, which supports the default
Ed25519 algorithm name. Previously permitted 1.0 installations lacked the
JWK import API, and 1.1 still rejected Ed25519; importing the plugin alone
did not reveal these actual-signing failures.
The CLI extra now requires Typer >=0.17.5. Earlier allowed releases could fail
before executing a command on modern union annotations or incompatible Click
versions. Generated memory/Mongo/Postgres scaffolds now wrap application
secrets in SecretStr; regenerate or make that small change in existing copies.
CI resolves installed wheels independently of uv.lock: core and every extra
are tested separately at minimum direct dependency versions on Python 3.11,
and at latest-compatible versions on Python 3.11, 3.12, and 3.13. Transitive dependencies
still obey their upstream constraints. This is compatibility testing, not a
recommendation to deploy the oldest dependency releases or an audit guarantee.
Account status, verification, and authentication age
Existing users default to active=True; upgrading does not suspend accounts.
Existing sessions have unknown authenticated_at=None, never a fabricated
migration timestamp. Password/OTP authentication establishes a timestamp;
refresh and access rotation preserve it. Legacy sessions therefore fail a
recent-authentication requirement until the user authenticates again.
auth.depends.verified_user()protects an application route requiring verified email. It returns a safeUserView.auth.depends.recent_session(max_age=timedelta(minutes=5))requires a known, sufficiently recent authentication and returns aSessionContext.await auth.policy.authenticate(token, require_verified=True, max_age=...)validates a real token and returns anAuthenticatedActorsnapshot. A model constructed by application code is not independently signed proof of access.await auth.policy.set_active(UserId(...), active=False, reason="...")is a trusted administrator operation, never a public user-editable endpoint. The application must authorize the administrator. Status changes publish a best-effort audit event and suspension revokes stored sessions/refresh tokens. Custom adapters need the optionalUserStatusStore.set_user_activecapability for this administrative method. Ordinaryupdate_usermust preserve stored account status so a stale profile update cannot reactivate a suspended user. The setter participates in user before/after-update hooks. Reactivation first clears leftover credentials if a prior suspension cleanup was interrupted; audit delivery remains best effort.
The opt-in SessionOptions.require_verified_user=True gates authenticated
session reads, password sign-in, and refresh. Signup can still issue a restricted
bootstrap session, but it does not grant protected-route access or refresh
before verification. Verification endpoints remain reachable to complete the
flow. The email_verification.require_verified_for_sign_in option also prevents
unverified email/password signup from issuing a session. It sends verification
email automatically and returns EmailVerificationRequiredResponse with
user and verificationRequired: true, without session or credential fields.
Both signup SDK methods now return AuthenticationResponse |
EmailVerificationRequiredResponse; narrow the result before using session or
credential fields. Ordinary signup with this option disabled is unchanged.
This option remains narrower than the session-wide policy and does not gate
previously issued sessions.
API-key verification always checks owner suspension. Its optional
ApiKeyOptions.require_verified_user adds verified-owner checks. User-editable
metadata and user-supplied API-key permissions are not trusted role/entitlement
storage; application resource authorization remains application-owned. An
optional policy_hook receives typed PolicyRequest and returns
PolicyDecision; it can deny, but cannot override suspension, verification, or
freshness checks. Automatic hook action names are password.sign_in,
session.issue, session.read, session.refresh, session.verified,
session.recent, api_key.create, api_key.update, and api_key.verify.
List/delete/user-mutation actions are not independently dispatched to this hook;
HTTP routes may already pass through session.read, while trusted ID-based SDK
operations remain application-authorized server calls.
JWT access tokens remain stateless. Logout/family revocation invalidates refresh credentials, not every already-issued JWT at external verifiers. FastAuth's own session reads additionally consult account policy. See the session guide for exact logical-session IDs, legacy behavior, rotation, and grace guarantees.
Typed API and plugin behavior changes
auth.otp, auth.verification, auth.jwt, and auth.audit expose typed async
services. Existing managers remain. Explicit None for a profile name or image
now clears it consistently with HTTP; omit the field to preserve it. Null
metadata and username are rejected. See the SDK guide for the full field matrix.
Plugin authentication, server-only, and supported CSRF declarations are enforced; unsupported security declarations fail startup. The global expired-API-key cleanup operation is server-only. Applications that depended on an accidentally public endpoint must move cleanup into an authorized maintenance job. These fail-closed changes and refresh invalidation are documented security exceptions to the usual deprecation window, not silent compatibility fallbacks.
Direct SDK calls still do not inherit router IP rate limiting automatically.
Use auth.actions.check/run at custom network boundaries with validated
proxy-aware metadata. Do not double-charge a built-in route's limiter.
Password work and operational budgets
Argon2 work runs off the event loop with a per-runtime bound. The default is two
concurrent operations; tune PasswordOptions.max_concurrent_operations together
with worker count, Argon2 memory cost, and available RAM. This does not lower
Argon2 work factors. A cancelled request retains its slot until the native work
finishes. Successful password verification can upgrade an outdated hash.
Injected synchronous hashers also run in the bounded worker executor, with
ContextVar values propagated. They must be thread-safe, or configured with
max_concurrent_operations=1. Automatic rehash uses the optional
PasswordRehashStore compare-and-swap capability; it safely skips adapters
without it. A concurrent password change that wins the CAS causes that login
to fail rather than overwrite the new password.
The current default minimum password length is 8; set min_length explicitly
for a stricter application policy. Session IP and user-agent fields are recorded
metadata, not cryptographic or request-time binding checks.
Email and audit delivery
Domain event handlers are awaited sequentially. Failures are logged and isolated from the authentication mutation; there is no durable event outbox, automatic redelivery, or exactly-once audit guarantee. Slow handlers still add latency. Do not use event handlers as the only authorization or transactional control.
The deployment recipes include an async production email sender with bounded retries, timeout, and provider idempotency. It awaits provider acceptance, not mailbox delivery, and is not a durable queue. Add an application-owned outbox for delivery guarantees across process failure.
Signup and profile input corrections
Email/password signup and profile update now trim submitted display names, reject
names longer than 100 characters after trimming, and treat blank or whitespace-only
names as None. Omitted profile fields still remain unchanged; explicit blank
names clear the name. These checks apply to both HTTP requests and typed commands.
Existing persisted names are not rewritten and remain readable; normalize legacy
values deliberately in your application if desired.
Passwords shorter than the configured minimum now return HTTP 400 with the typed
PASSWORD_TOO_SHORT code and a message containing that minimum. Python callers
can catch PasswordTooShortError, a subclass of InvalidRequestError, and inspect
its min_length attribute. Update clients that matched only INVALID_REQUEST.
Duplicate signup emails retain HTTP 409 and DUPLICATE, with the message
βAn account with this email already exists.β This deliberately preserves signup's
existing account-discovery behavior; password recovery continues to hide whether
an account exists. Do not use signup as a non-enumerating endpoint.
MongoDB driver security update
The beanie extra now requires pymongo>=4.18.3,<5; the project lockfile uses
4.18.3. This applies the upstream fixes for the reported PyMongo security issues
and prevents clean consumers from resolving affected older driver versions.
PyMongo 4.18 no longer supports MongoDB 4.2: MongoDB 4.4 or newer is required.
Upgrade older servers before installing this dependency update, following MongoDB's
supported server upgrade path and testing on a backup first. No automatic database
server upgrade or data migration is performed by this change.