OAuth login sequence
User, app, and identity provider exchanging tokens.
OAuth is one of those flows that everyone half-remembers and nobody can draw from scratch in a meeting. This template lays out the authorization code flow in eight messages: the sign-in click, the redirect to the identity provider, consent, the auth code coming back, and the server-side exchange that turns that code into access and refresh tokens.
The participant cast is deliberately minimal — user, app, identity provider — because that's the level at which most architecture discussions happen. Dashed return arrows mark responses, so the asymmetry between front-channel redirects and the back-channel token exchange is visible at a glance.
When to use this template
- Designing a new login integration — agree on the flow with your team before writing code, and decide early where tokens are stored and which scopes you actually need.
- Security reviews — auditors and pentesters ask for exactly this diagram. Showing the code-for-tokens exchange happening server-side answers half their questions up front.
- Explaining OAuth to newcomers — the consent screen and the two-redirect dance make far more sense as lifelines and arrows than as prose in an RFC.
How to adapt it
Rename the generic Identity Provider to your real one — Google, GitHub, Okta, Auth0 — and then make the flow match your implementation:
- Add PKCE parameters (code_challenge, code_verifier) to the redirect and exchange messages if you're building a public client.
- Insert a session creation step after the token response, showing your app setting a cookie before redirecting the user.
- Add a token refresh exchange at the bottom to document what happens when the access token expires.
You can make all of these changes by editing the diagram visually — visual edits regenerate clean Mermaid code, so the result drops straight into your auth documentation or pull request description.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
actor User
participant App
participant IdP as Identity Provider
User->>App: Click "Sign in"
App->>IdP: Redirect with client_id + scope
IdP->>User: Show consent screen
User->>IdP: Approve
IdP->>App: Redirect with auth code
App->>IdP: Exchange code for tokens
IdP-->>App: Access + refresh tokens
App-->>User: Signed in
Frequently asked questions
- What is an OAuth sequence diagram?
- It's a sequence diagram showing the message exchange of an OAuth flow over time: the user clicking sign in, the redirect to the identity provider with client_id and scope, the consent screen, the authorization code coming back, and the server-side code-for-tokens exchange. Reading top to bottom gives you the exact order of redirects and API calls.
- What is the difference between the auth code and the access token?
- The authorization code is a short-lived, single-use value the identity provider sends back through the browser redirect — it proves the user approved access but grants nothing by itself. The app then exchanges it server-to-server for an access token (used to call APIs) and a refresh token. Splitting the two steps keeps tokens out of browser URLs and logs.
- Why does the diagram show two redirects between the app and the identity provider?
- Because the authorization code flow makes two front-channel trips: first the app redirects the user's browser to the provider with its client_id and requested scopes, then after consent the provider redirects back with the auth code. The final token exchange happens on the back channel, which is why it's drawn as a direct request rather than a redirect through the user.
- How do I extend this diagram for PKCE or refresh token rotation?
- For PKCE, add the code_challenge to the first redirect message and the code_verifier to the token exchange — two label edits, no new participants. For refresh rotation, append a second exchange after the sign-in: App sends the refresh token to the IdP and receives a new access plus refresh pair. Both fit naturally below the existing lifelines.