How OAuth Works — authorization code flow
How OAuth works, shown on an interactive canvas: the authorization code flow between the user, a client application, the authorization server and the resource server.
OAuth lets one application access another service's data on a user's behalf without ever seeing the user's password — by trading consent for a short-lived token.
How OAuth Works — authorization code flow
The interactive FlowJam canvas for this explanation — every lane, row and arrow above is a real QueryChart diagram you can open and edit.
How to read this visual
- Read the three columns left to right: Authorization, Token exchange, Protected resource.
- Each row is one party's part of the story — the user's row sits at the top and the resource server's at the bottom, so the user's consent and the server's validation bracket the middle.
- Arrows that jump rows, like the code returning to the client, are real network messages between parties; arrows within a row are that party's own steps.
The authorization dance
"User clicks "Sign in with provider"" starts in the user's row and hands to "Client redirects the user to the authorization server". The redirect is OAuth's defining move: it takes the user OUT of the client app to the provider, where "User signs in and approves the requested scopes" happens. The consent screen — not just the login — is the step that matters: the user chooses exactly what the client may do. "Authorization server returns an authorization code to the client" brings control back to the app, but only with a code, not a token.
The token exchange
"Client exchanges the code and its secret for an access token" crosses from the client row into the authorization server's. This step is where the client proves it is a legitimate application by presenting the code it received AND its registered client secret — so a stolen code alone is not enough. "Authorization server issues the access token" is the moment the consent decision becomes a capability: a string that says what the client may do, for how long.
Spending the token
"Client calls the resource server with the access token" crosses into the "Resource server" cluster, and "Resource server validates the token and returns the user's data" is the payoff. The resource server never sees the user's password or the consent screen — it only checks the token. "User sees their data inside the app" closes the loop back in the user's row: from the user's perspective, they signed in once and the app got their data.
Key relationships and takeaways
- The user's password is given to the authorization server only — the client and resource server never see it.
- Consent (the scopes) is the actual grant; the access token is that grant in machine-readable form.
- The authorization code is short-lived and useless without the client secret — two factors protect the exchange.
- Access tokens expire; refresh tokens quietly mint new ones without another consent screen.
- The resource server's only job is validating the token, which keeps the parties decoupled.
When to use this visual
- Explaining to a product team why "Sign in with Google" is safe and what the consent screen asks for.
- Choosing an OAuth flow: the authorization code flow here vs. implicit or client-credentials for other scenarios.
- Auditing where user credentials and tokens actually travel in your integration.
How it works
Rename the parties to your system
Replace the four clusters with your real participants — your web app, your identity provider, your API — so the boundaries reflect the system you are documenting.
Add the scopes you request
Annotate the consent step with the actual scopes and a note on why each is needed, so reviewers can see the least-privilege decision.
Draw the refresh path
Add a branch after token expiry: the client presents the refresh token and receives a new access token without a consent screen, ending in its own explicit state.
Model the failure cases
Add the reject branches — a denied consent screen, an invalid code, an expired or revoked token — each with the error response it produces.
Frequently asked questions
What is OAuth and why does it exist?
OAuth is a delegation standard. It lets an application access a user's data on another service on the user's behalf without the application ever seeing the user's password. The user authenticates once at the authorization server and approves specific permissions (scopes); the app receives a token it can spend. That separation of concerns is exactly what the four clusters in the visual represent.
What is the difference between an authorization code and an access token?
An authorization code is a short-lived intermediate value the client receives after the user's consent; on its own it grants nothing. The client exchanges the code — along with its registered client secret — for an access token, which is the actual capability used to call the resource server. The two-step exchange is what lets the client prove its identity at the token endpoint.
Why doesn't the user give their password to the app?
Because the app only needs limited, revocable access — reading a profile, not owning an account. If the app received the password it would have full access forever, and the user could not revoke one app without changing their password everywhere. OAuth trades a password for a scoped, expiring token the user can revoke independently.
What are scopes?
Scopes are the specific permissions the user grants, such as "read email" or "write to calendar". They appear on the consent screen and are encoded into the access token. The resource server enforces them, so a token scoped to reading cannot write — least privilege is built into the protocol rather than relying on the client's good behaviour.
Edit this visual in QueryChart (FlowJam)
Open this exact OAuth flow canvas as your own chart, rename the parties to your services, and annotate the scopes you request.