OAuth Flow Diagram Guide

An OAuth flow diagram shows how a user grants an application access to their data on another service without handing over their password. It draws four parties and the order in which they talk: the resource owner (the human), the client (your app), the authorization server (the thing that issues tokens), and the resource server (the API holding the data).

Naming those four correctly is most of the value. The single most common mistake in OAuth diagrams is collapsing the authorization server and the resource server into one box labelled "Google". They are different systems with different jobs — one decides who you are and what you may do, the other serves data and checks the token it was handed. Once they are one box, the diagram can no longer show the thing that matters: which of them ever sees the user's password (only the first) and which only ever sees a token (only the second).

The other reason to draw it is that OAuth is a redirect protocol, and redirects are invisible in code. Reading a handler tells you what happens at one endpoint; it does not tell you that the browser bounced through three origins carrying a state parameter that must come back unchanged. A sequence diagram makes the bounce visible, which is why almost every real OAuth bug — mismatched redirect_uri, dropped state, code replayed twice — is obvious in a diagram and invisible in a stack trace.

If you have read the RFC's diagram and still cannot draw your own, that is expected: the spec draws the abstract protocol. Your diagram needs the parts the spec leaves as an exercise, which is what the examples below are.

Five things. The first one is the one that separates a useful OAuth diagram from a redrawn spec figure:

Here is the skeleton — authorization code, no error branches, four separate participants. Every example below is this diagram with one specific thing added.

Three steps. Step 1 is where most diagrams go wrong, and it takes about two minutes.

"OAuth" is not one flow, and drawing a generic one produces a diagram that is wrong for every specific case. Answer one question — is there a human present at the moment the token is issued?

If yes, you are drawing authorization code with PKCE. This is the answer for web apps, single-page apps and mobile apps alike. It has been the answer for every browser-based client since PKCE became mandatory for public clients; if you find a tutorial drawing implicit flow (token returned straight in the redirect URL), it predates that and you should not copy it.

If no — a cron job, a service syncing with a partner API — you are drawing client credentials, and your diagram has no user lifeline at all. That absence is information: it is why there is no consent screen and no refresh token.

Everything else (device code for TVs, token exchange between services) is a variation you will know you need. Pick one and draw only it. A diagram covering two flows at once covers neither.

Go through your arrows and sort each one into two piles: the browser carries this and our server calls this directly.

The sort is mechanical — anything that is a redirect, a URL the user's address bar shows, or a form the user submits, is front channel — but the result is the whole point of the protocol. The front channel is observable: it is in browser history, in Referer headers, in server logs, potentially on a shared machine's screen. That is exactly why the authorization code goes through it and the access token does not. The code is short-lived, single-use, and useless without the client secret or a PKCE verifier — it is designed to survive being seen.

Once sorted, check one thing: is there anything on the front channel that would be damaging if a stranger read it over your shoulder? If yes, that is a finding, and it is the kind this diagram exists to produce.

Describe the handshake in sentences and let text2diagram lay it out — "the app redirects the browser to the authorization server with a code challenge, the user logs in and approves, the server redirects back with a code, the app exchanges the code plus the verifier for tokens at the token endpoint" comes back as an editable sequenceDiagram.

Or open one of the examples below in the editor and rename the participants to your provider. The arrangement is the part that is hard to get right; Authorization Server → Okta is a find-and-replace.

Three flows the spec's figure does not draw for you: the modern default, what happens when a token expires, and what it looks like when there is no user at all.

The two arrows worth studying are the first and the last. The app generates a code_verifier and sends only its hash (code_challenge) through the front channel; at the end it sends the verifier itself through the back channel. An attacker who steals the code out of a redirect has the code but not the verifier, so the exchange fails — that is the entire idea, and it is legible in the diagram in a way it is not in prose.

Also note the check state matches self-arrow. It is not a network call, so people leave it out; leaving it out is how CSRF on the callback endpoint ships. A step that guards something deserves a box even when nothing crosses the wire.

This is the flow teams skip and then debug at 2am. Access tokens expire constantly, so this path runs far more often than the login above — and it has a branch most diagrams omit.

With rotation, each refresh burns the old token and issues a new one. That turns a stolen refresh token into a detectable event: if RT1 is presented twice, either the attacker or the real client is using a token the server already retired, and the server cannot tell which. The only safe response is to revoke the whole family and force a fresh login. Drawing that second branch is what turns "we rotate refresh tokens" from a checkbox into a behaviour with a defined outcome.

The shape to notice is what is missing: no browser lifeline, no consent screen, no redirect, no front channel at all. Every arrow here is server to server, which is why this flow is allowed to use a plain client secret and why PKCE has nothing to do here.

The branch worth drawing is the boring one — the token expiring partway through a long batch. It is boring right up until a nightly sync half-completes and leaves two systems disagreeing, at which point everyone wants to know whether the job re-authenticates and resumes or gives up. The diagram answers that in one glance.