Beyond Login: Building a Production Authentication Lifecycle in FastAPI

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 a