2FA Flow Diagram Guide

A 2FA flow diagram shows what happens between "the password was correct" and "the user is signed in" — the second factor. It is a sequence diagram, because the step involves several parties that are easy to conflate: your app, whatever verifies the code, and the thing that produces the code, which is usually not under your control at all.

The single idea that makes this diagram worth drawing is that 2FA splits login into two transactions, and creates a state between them. After the password check the user is neither logged out nor logged in. They are something else — half authenticated — and that state needs its own short-lived credential, its own expiry, and its own attempt counter. Diagrams that skip it draw an arrow straight from "password ok" to "enter your code" and quietly imply that the server is holding the user's identity in a variable somewhere. That implication is where most real 2FA vulnerabilities live.

The second reason is that this flow is mostly failure branches. The happy path is four arrows and nobody argues about it. What teams argue about — and what support tickets are made of — is: how many wrong codes before we lock the account, what happens when the SMS never arrives, what a user does when their phone is in a river, whether an old code can be replayed. Every one of those is a branch, and a branch you have not drawn is a branch someone will improvise in a hotfix.

This page draws only the second factor. The password step appears in the skeleton just to show where the handoff is.

Six things. The first is the one that separates a real diagram from a marketing illustration:

The skeleton, with no failure branches at all. Notice how short it is — that is the entire happy path, and it is why a diagram that stops here tells you almost nothing.

Three steps. Step 2 is where the diagram stops being a picture and starts being a review.

The three common second factors produce three different diagrams, and the difference is entirely about which participants you do not control:

TOTP (authenticator app) — the code generator is an app on the user's phone with no network connection to you. It never appears in an arrow to your server. Your diagram has a lifeline that only ever talks to the user.

SMS — there is a third-party gateway in the middle, which means an extra participant, an extra failure mode (delivery), and an extra cost per attempt that makes resend rate limits a business decision, not just a security one.

Passkeys / hardware keys — the browser mediates, and the interesting arrows are challenge and signature rather than a code a human retypes. Different enough that it deserves its own diagram, not a branch in this one.

Pick one per diagram. If you support two, draw two — the moment you fold SMS fallback into a TOTP diagram, both paths get harder to read, and the fallback is exactly the path an attacker will aim for.

Unusually for a diagram, start from the bottom. Write down every way this can fail before you draw a single successful arrow:

- wrong code, retries remaining - wrong code, retries exhausted - correct code, but too late (outside the window) - correct code, but already used - correct password, wrong username — does the response differ? It must not - the code never arrived (SMS only) - the user no longer has the factor at all

Now draw the happy path, and hang each failure off the arrow where it is detected. Doing it in this order matters: build the success path first and the failures get bolted on wherever there is room, which produces a diagram that is technically complete and useless for finding the gap. Build the failures first and the gap is the branch you could not attach anywhere.

The fifth item is the one that catches people. If a wrong username and a wrong password produce visibly different responses — different text, different status, noticeably different timing — the login page is a username oracle, and the 2FA step is where this most often leaks, because it is tempting to say "this account requires a code" before the password is even checked.

Describe it in sentences and let text2diagram lay it out — "after the password is verified the server returns a pre-auth token valid five minutes, the user reads a code from their authenticator app and submits it, the server checks it against the shared secret, marks it consumed and issues a session; after five wrong codes the pre-auth token is burned" comes back as an editable sequenceDiagram with the alt blocks already in place.

Or open one of the three below and rename the participants. The branch structure is the part worth keeping.

Three diagrams: the common case done properly, the one with a third party in it, and the one that has to happen before either can.

Three details here are worth copying. The pre_auth_token with its five-minute life is the half-authenticated state from the list above, made concrete. mark this code consumed is the replay guard — one self-arrow, easy to leave out, and its absence means a shoulder-surfed code works for the rest of its window.

The third is the first branch: when the password is wrong, the response says nothing about whether 2FA is enabled. That has to be true even though the server already knows, and it is the reason the branch sits above the pre-auth token rather than after it. Diagrams that check 2FA status first are documenting an account-enumeration endpoint.

Note also that the authenticator app never has an arrow to the server. Both sides compute the same six digits from a secret they agreed on at enrollment, and never speak again.

The extra participant changes the diagram in a way people underestimate. The gateway accepting your request (queued) is not the same event as the phone receiving the message, so there are two arrows, and the second one you cannot observe. That gap is why "resend" exists as a feature and why it needs a rate limit — drawn here as a note rather than a branch, because it governs the whole interaction rather than one step.

The failure branch is the one worth arguing about in review: when the gateway is down, does the user get a backup method or a dead end? Every SMS 2FA system needs an answer, and a surprising number of them answer "dead end" simply because nobody drew this arrow.

The flow everyone implements second and draws never. Two things in it are load-bearing.

The secret stays pending until a code proves it works. Activating 2FA the moment the QR code is displayed locks out every user who closes the tab before scanning — a self-inflicted support queue. The status pending on that self-arrow and the rejection branch at the bottom are the same decision seen from two sides.

Recovery codes are minted here or nowhere. This is the only moment in the entire system where the user is both authenticated and not yet dependent on the new factor, which makes it the only safe place to hand out the way back in. Note shown once — they are stored hashed, exactly like passwords, so this screen genuinely cannot be re-rendered later.