DEV Community: HoungDev

Beyond Login: Building a Production Authentication Lifecycle in FastAPI

HoungDev — Sun, 09 Aug 2026 09:29:37 +0000

Authentication is often presented as a short sequence:

Accept a username and password.
Return a JWT.
Protect a few endpoints.

That is enough for a tutorial, but it is not an authentication lifecycle.

Real applications must also answer harder questions:

How is an email address verified without storing a reusable secret?
What happens to existing sessions after a password reset?
Can a user see and revoke a lost device?
How do we prevent a rotated refresh token from being replayed?
How should TOTP secrets and recovery codes be stored?
How can an OIDC identity be linked without trusting email matching?

I explored those questions while building
FastAPI Production API v1.2.0,
a backward-compatible authentication lifecycle release for an open-source
FastAPI backend foundation.

This article explains the design decisions behind it—not just the endpoints
that were added.

1. Model lifecycle tokens as scoped, single-use credentials

Email verification and password recovery look similar from the outside: send a
link, receive a token, and update an account. Treating them as interchangeable,
however, creates unnecessary risk.

The release uses account-action tokens with four important properties:

Random: the token is generated as an opaque secret rather than derived from user data.
Scoped: a verification token cannot be used as a password-reset token.
Expiring: every token has a short, configurable lifetime.
Single use: confirmation atomically marks the token as consumed.

Only a hash of the token is persisted. The original value exists only long
enough to be delivered to the user.

This gives email verification and password reset a shared security primitive
without making their policies identical.

The main endpoints are:

POST /auth/email-verification/request
POST /auth/email-verification/confirm
POST /auth/password-reset/request
POST /auth/password-reset/confirm

Both request operations return uniform responses. A caller should not be able
to determine whether an email belongs to an account by comparing status codes
or response bodies.

2. Treat password reset as a session-security event

Changing a password is not only a database update. If a stolen refresh token
remains valid afterward, the attacker may keep creating new access tokens even
though the account owner completed recovery.

A successful reset therefore performs one transaction that:

validates and consumes the scoped reset token;
replaces the password hash;
consumes other outstanding reset tokens; and
revokes every refresh-token session for the account.

The endpoint does not issue a new authenticated session. The user signs in
again with the new password.

There is an important boundary here: existing stateless access tokens remain
valid until their short expiration time. Immediate access-token invalidation
would require a denylist, token-version check, or a move toward opaque tokens.
Documenting that boundary is part of the security design.

3. Use refresh-token families to represent device sessions

A table of individual refresh tokens does not naturally answer “Which devices
are signed in?” Token rotation creates a chain of records, while the user thinks
in terms of sessions.

v1.2.0 groups rotated refresh tokens into a family:

login
  -> create family A for "Work Laptop"
  -> issue refresh token A1

refresh A1
  -> revoke A1
  -> issue A2 inside family A

This family becomes the device-session boundary. It supports:

GET    /auth/sessions
DELETE /auth/sessions/{session_id}
DELETE /auth/sessions

Device labels are bounded and normalized before storage. Session responses
expose useful metadata without returning token hashes or raw credentials.

The family also improves replay handling. If a refresh token that was already
consumed by rotation appears again, the live family is revoked. The system
treats reuse as possible token theft rather than an ordinary validation error.

Logout revokes the full family, not only one token record. Password reset, MFA
changes, and external-identity changes can revoke all relevant families through
the same session abstraction.

4. Add TOTP without turning the seed into a password

TOTP verification requires access to the shared secret, so hashing the seed is
not sufficient. The implementation encrypts TOTP seeds at rest using a
dedicated application key.

Recovery codes have different requirements. They only need comparison, so the
database stores hashes and shows the original codes once when they are created.
Each recovery code is single use.

Enrollment is a two-step process:

POST /auth/mfa/totp/enroll
POST /auth/mfa/totp/confirm

The first operation creates a pending encrypted secret. MFA is not enabled
until the user proves possession by submitting a valid code.

After enrollment, password login no longer returns access and refresh tokens
immediately. It returns a short-lived opaque challenge:

password accepted
  -> mfa_required
  -> challenge_token
  -> TOTP or unused recovery code
  -> local access and refresh tokens

The service records the last accepted TOTP counter and rejects the same or an
older counter. This prevents a valid code from being replayed inside the
accepted clock window.

Access tokens include authentication-method and authentication-time claims.
Those claims provide a foundation for requiring recent MFA before sensitive
operations. Refreshing a session intentionally does not manufacture a recent
MFA event.

TOTP is useful, but it is not phishing resistant. WebAuthn/passkeys remain the
stronger direction for applications with that requirement.

5. Make OIDC linking an explicit security ceremony

OIDC login uses the Authorization Code flow with:

PKCE S256;
random state;
OIDC nonce;
exact configured redirect URIs;
browser-bound authorization transactions; and
strict issuer, signature, audience, authorized-party, and nonce validation.

The database stores hashes of state, nonce, and browser binding. The
transaction-specific PKCE verifier must later be sent to the provider, so it is
encrypted rather than hashed.

External accounts are identified by the immutable pair (issuer, subject).
Provider email is useful profile data, but it is not the identity key.

Most importantly, an existing local account is never silently linked because
an OIDC provider returned the same email address. Automatic email matching can
turn a provider mistake or account-reassignment edge case into account takeover.

Linking is therefore explicit and authenticated:

POST /auth/oidc/link/authorize
GET  /auth/oidc/callback
GET  /auth/oidc/identities
DELETE /auth/oidc/identities/{identity_id}

Sensitive link and unlink operations require recent authentication and revoke
refresh sessions after the identity set changes. The application also prevents
a user from removing their last available sign-in method.

OIDC does not bypass local MFA. If a linked local account has MFA enabled, a
successful provider response produces the same second-factor challenge used by
password login.

What made this a release rather than a demo?

The implementation was shipped through five focused slices:

Email identity and verification
Password recovery and session revocation
Refresh-token families and device sessions
TOTP MFA and recovery codes
OIDC login and explicit account linking

Every slice included tests, documentation, failure paths, and migration checks.
The final v1.2.0 release passed:

144 automated tests;
92.85% coverage against a 90% gate;
linting and formatting checks;
Alembic migration and rollback validation;
dependency auditing;
source distribution and wheel builds; and
an isolated wheel installation and application-version smoke test.

The release also publishes SHA-256 checksums alongside the Python artifacts.

Try it or review the design

Repository:
github.com/HoungDev/fastapi-production-api

Release:
FastAPI Production API v1.2.0

The project is intended as a security-focused reference foundation, not a claim
that one authentication policy fits every production system. Provider setup,
email delivery, secret management, token lifetimes, access-token invalidation,
and threat models still need application-specific decisions.

I would especially value feedback on the refresh-family model, MFA step-up
claims, and OIDC linking rules.

I also shared the release summary on
LinkedIn.

What authentication lifecycle failure mode has caused the most trouble in your
own systems?

Designing a Safer Batch Image Renamer in Python

HoungDev — Fri, 07 Aug 2026 11:23:34 +0000

Batch-renaming images sounds like a five-line script—until a destination already exists, a rename fails halfway through, or you need to recover the original filenames.

I ran into that design problem while building Creator Toolkit CLI, an open-source Python CLI for small creator workflows. The interesting part was not generating image_1.jpg; it was making the operation inspectable before it ran and recoverable afterward.

This article walks through the safety model shipped in Creator Toolkit CLI v0.1.0: deterministic planning, dry runs, collision checks, two-phase renaming, rollback, and undo manifests.

Why the obvious loop is risky

A first implementation might look like this:

from pathlib import Path

for index, source in enumerate(Path("images").glob("*.jpg"), start=1):
    source.rename(source.with_name(f"image_{index}.jpg"))

It is short, but it leaves several questions unanswered:

Is the input order stable across systems?
What happens if image_1.jpg already exists?
What if that file is also one of the sources that should move?
What happens when the third rename fails after two succeeded?
Can a user preview the exact plan?
Can the operation be reversed later?

For file mutations, those are not edge cases. They are the design.

1. Separate planning from mutation

The first rule is simple: build the complete plan without changing the directory.

Creator Toolkit selects supported files, sorts them case-insensitively, and returns explicit (source, destination) operations:

SUPPORTED_EXTENSIONS = {".jpeg", ".jpg", ".png"}


def plan_image_renames(folder: Path) -> list[tuple[Path, Path]]:
    images = sorted(
        (
            item
            for item in folder.iterdir()
            if item.is_file() and item.suffix.lower() in SUPPORTED_EXTENSIONS
        ),
        key=lambda item: item.name.casefold(),
    )

    operations = [
        (source, folder / f"image_{index}{source.suffix.lower()}")
        for index, source in enumerate(images, start=1)
    ]
    return [(source, destination) for source, destination in operations if source != destination]

Planning separately gives the CLI one source of truth for preview, confirmation, JSON output, application, and tests.

Users can inspect that plan without touching a file:

creator-toolkit rename ./images --dry-run

Example output:

Planned 2 image(s).
cover.jpg -> image_1.jpg
thumbnail.png -> image_2.png

A dry run is much more useful when it exercises the same planning path as the real operation. A separate “preview approximation” can drift from the code that eventually mutates the filesystem.

2. Validate the whole plan before the first rename

Before applying anything, the implementation checks that:

every source is unique and still exists;
every destination is unique;
each operation stays inside the same directory; and
an existing destination is either another source in the plan or a collision that must stop the operation.

That last distinction matters. Consider this directory:

cover.jpg
image_1.jpg

The desired plan may be:

cover.jpg   -> image_1.jpg
image_1.jpg -> image_2.jpg

image_1.jpg exists, but it is also scheduled to move. Rejecting every existing destination would incorrectly reject a valid plan. Overwriting it would be worse.

Complete-plan validation lets us distinguish a movable destination from an unrelated file that must never be overwritten.

3. Use a two-phase rename

Even a valid plan can fail if it is applied directly in source order. Creator Toolkit therefore uses two phases:

Move every source to a unique temporary name in the same directory.
Move each temporary file to its final destination.

Conceptually:

cover.jpg   -> .creator-toolkit-stage-<uuid>.tmp
image_1.jpg -> .creator-toolkit-stage-<uuid>.tmp

.creator-toolkit-stage-<uuid>.tmp -> image_1.jpg
.creator-toolkit-stage-<uuid>.tmp -> image_2.jpg

Once phase one completes, all final destination names are free. This avoids order-dependent collisions without relying on platform-specific overwrite behavior.

The temporary files remain in the target directory so each move stays on the same filesystem. That avoids cross-device rename failures and keeps the operation local to the directory being changed.

4. Roll back both failure points

There are two different failure windows, so they need two recovery paths.

If staging fails, files that already reached temporary names are restored to their original names in reverse order.

If finalization fails, the state is mixed: some files have final names, while others still have temporary names. The implementation stages that mixed set again and then restores every original source name.

The important principle is broader than this project:

A multi-step filesystem mutation should define recovery for every intermediate state it can create.

Rollback is still best effort. Filesystems and external processes can fail in ways an application cannot fully repair. The CLI reports a distinct runtime error if restoration also fails, and the documentation still recommends a separate backup for valuable assets.

5. Write recovery metadata before applying

Interactive confirmation protects the current command, but it does not help tomorrow. Applied CLI renames therefore create a unique JSON manifest in the image directory.

A simplified manifest looks like this:

{
  "version": 1,
  "status": "applied",
  "created_at": "2026-08-07T12:00:00+00:00",
  "directory": "/absolute/path/to/images",
  "operations": [
    {
      "source": "cover.jpg",
      "destination": "image_1.jpg"
    },
    {
      "source": "thumbnail.png",
      "destination": "image_2.png"
    }
  ],
  "applied_at": "2026-08-07T12:00:01+00:00"
}

The manifest is first written with status: "pending", then changed to applied or failed. Manifest writes themselves use a temporary file followed by a replace operation, so an interrupted write is less likely to leave truncated JSON at the final path.

To preview a restore:

creator-toolkit undo ./images/.creator-toolkit-renames-<timestamp>-<id>.json --dry-run

To apply it:

creator-toolkit undo ./images/.creator-toolkit-renames-<timestamp>-<id>.json

Undo reverses the concrete operations stored in the manifest. It does not try to reconstruct intent from the current directory.

6. Treat the manifest as untrusted input

A recovery file can become dangerous if the program blindly trusts paths inside it.

Before undoing, Creator Toolkit checks the manifest version and status, requires an absolute target directory, and accepts only plain filenames for each operation. Values such as ../outside.txt are rejected because Path(value).name != value.

The reversed plan then passes through the same collision validation as a normal rename. If a new file now occupies an original filename, undo stops instead of overwriting it.

That makes the manifest useful recovery metadata, not a general-purpose instruction file for moving arbitrary paths.

7. Make automation explicit

Human-readable previews are useful at a terminal. Scripts need a stable contract.

Every scriptable subcommand supports JSON output:

creator-toolkit rename ./images --dry-run --json

Successful responses use a versioned envelope, while validation and runtime errors go to standard error as structured JSON. Exit codes distinguish success, runtime failure, and unsafe CLI usage.

JSON mode also never prompts. A mutating rename or undo must include either --dry-run or --yes; otherwise the command exits with a usage error. Automation should never hang while waiting for an interactive answer it cannot provide.

Try the released version

Creator Toolkit CLI v0.1.0 requires Python 3.11 or newer:

python -m pip install creator-toolkit-cli==0.1.0

Start with a disposable directory and a preview:

creator-toolkit rename ./images --dry-run

Then review the plan before applying it:

creator-toolkit rename ./images

The source, tests, JSON contract, and release artifacts are available here:

This article intentionally targets the released v0.1.0 tag. The main branch may contain unreleased changes.

Closing thought

The core algorithm is not large. The reliability comes from the boundaries around it: plan first, validate globally, isolate intermediate states, define rollback, persist recovery metadata, and make automation behavior explicit.

If you have handled batch file mutations differently, I would be interested in the failure cases and recovery strategies that shaped your design.