The OAuth 2.0 authorization code flow lets an app act on a user’s behalf without ever seeing their password. The user signs in at the authorization server, and the app receives a short-lived, one-time authorization code through the browser. The app then trades that code for an access token in a direct server-to-server request.
When people say “the OAuth 2.0 flow”, this is usually the one they mean. With PKCE added, it is the recommended flow for web apps, single-page apps, mobile apps and desktop apps alike.
The flow at a glance
- Redirect to the authorization server. The client sends the user’s browser to the authorization endpoint.
- Sign-in and consent. The user authenticates on the authorization server’s own pages and approves the requested access.
- Code returned. The authorization server redirects the browser back to the client with an authorization code.
- Code exchanged for tokens. The client sends the code to the token endpoint over a direct back-channel request.
- API calls. The client uses the access token to call protected APIs, and uses a refresh token (if issued) to get new access tokens.
The key point is that the authorization endpoint returns a code, never an access token. Tokens only come from the token endpoint.
What travels where
| Item | Channel | Who sees it |
|---|---|---|
Authorization request (client_id, scope, state, code_challenge) | Front channel (browser redirect) | Browser, client, authorization server |
| User’s password | Authorization server’s pages only | User and authorization server, never the client |
| Authorization code | Front channel (redirect back) | Browser, client |
code_verifier, client secret | Back channel (direct POST) | Client and authorization server |
| Access token, refresh token | Back channel (token response) | Client and authorization server |
The Flow with Real Requests
Here is what each step looks like on the wire, following RFC 6749 section 4.1, with PKCE from RFC 7636. In this example the client is https://app.example.com and the authorization server is https://auth.example.com.
1. Redirect the user to the authorization endpoint
The client first generates two random values. The first is a state, which protects against CSRF. The second is a code_verifier. It then sends the browser to:
GET /authorize?response_type=code &client_id=my-app &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback &scope=openid%20profile%20orders.read &state=af0ifjsldkj &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256 HTTP/1.1Host: auth.example.comcode_challenge is BASE64URL(SHA256(code_verifier)). The verifier itself never leaves the client at this stage.
| Parameter | Purpose |
|---|---|
response_type=code | Asks for an authorization code (this is what makes it the code flow) |
client_id | Identifies the registered client |
redirect_uri | Where the server sends the browser back; must match a registered value |
scope | The access being requested |
state | Random value that ties the callback to this request |
code_challenge / code_challenge_method | PKCE: a hash of the secret verifier, and the hash method (S256) |
2. The user signs in and consents
The user authenticates and approves the requested scopes on the authorization server’s own pages. The client never sees the password.
3. The server redirects back with a one-time code
HTTP/1.1 302 FoundLocation: https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkjBefore going any further, the client must check that state matches the value it generated.
4. The client exchanges the code for tokens
The client makes a direct back-channel request to the token endpoint:
POST /token HTTP/1.1Host: auth.example.comContent-Type: application/x-www-form-urlencodedAuthorization: Basic bXktYXBwOm15LXNlY3JldA==
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXkThe Authorization: Basic header carries the client ID and secret (my-app:my-secret, Base64-encoded). See HTTP Basic Authentication Explained for how that header is built.
A public client, such as a single-page or mobile app, has no secret. It omits the header, sends client_id in the body, and relies on PKCE alone.
5. The server returns the tokens
{ "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", "scope": "openid profile orders.read"}The request included the openid scope. Because of that, an OpenID Connect provider will also return an id_token in this response. That token tells the app who signed in, while the access token is for calling the API.
6. The client calls the API
The client sends Authorization: Bearer <access_token> with each API request. When the access token expires, it uses the refresh token to get a new one without involving the user.
Why PKCE Is Now Recommended for Every Client
PKCE was first designed for mobile apps, which cannot keep a client secret. Suppose an attacker intercepts the authorization code, for example through a malicious app registered for the same redirect URI. They still cannot redeem it, because the token endpoint demands the code_verifier that only the real client knows.
The OAuth 2.0 Security Best Current Practice (RFC 9700) and the OAuth 2.1 draft now recommend PKCE for confidential server-side clients as well. OAuth 2.1 also drops the implicit flow entirely. See OAuth 2.0 Grant Types Explained for how the other grant types compare and where PKCE fits.
Why the Server Returns a Code, Not an Access Token
The browser is the least trustworthy part of the flow. Anything sent through a redirect can end up in browser history, logs, referrer headers or a malicious extension. Returning a code instead of a token keeps the valuable credential off that path, for three reasons:
- Less token exposure. The code is short-lived and single-use, and it is useless without the client’s credentials or PKCE verifier. If it leaks, the damage is limited. A leaked access token, by contrast, can be used immediately.
- The client proves who it is. At the token endpoint, the client authenticates with its secret, its PKCE verifier, or both before receiving any tokens. A redirect alone cannot provide that check.
- Clear separation of jobs. The authorization endpoint handles the user: sign-in and consent. The token endpoint handles the client: verifying the code and credentials, then issuing tokens. Each endpoint can be secured for its own job.
Benefits of the Authorization Code Flow
- Tokens stay off the front channel. Access and refresh tokens are only returned over the back-channel token request.
- User consent. The user decides which scopes the client gets, on the authorization server’s own pages.
- Works for every client type. Web, single-page, mobile and desktop apps can all use it; public clients use PKCE instead of a secret.
- Refresh token support. Clients can get new access tokens without sending the user through sign-in again.
- Foundation for OpenID Connect. Sign-in with OIDC is this same flow with the
openidscope and an ID token added.
Common Mistakes to Avoid
- Skipping the
statecheck. If the client accepts any callback, an attacker can inject their own code (CSRF). - Loose redirect URI matching. Register exact redirect URIs. RFC 9700 recommends exact string matching on the server.
- Using
code_challenge_method=plain. UseS256;plainsends the verifier in the open. - Putting a client secret in a single-page or mobile app. Code shipped to users cannot keep a secret. Treat these apps as public clients and rely on PKCE.
- Still using the implicit flow. It returns the token in the URL. Move single-page apps to the code flow with PKCE.
FAQ
What is the difference between the authorization code and the access token?
The authorization code is a short-lived, single-use value that travels through the browser and is useless on its own. The access token is the credential that calls the API, and it is only ever returned over the back-channel token request.
Should a single-page app use the authorization code flow?
Yes, with PKCE. Single-page apps used to rely on the implicit flow, which returns the token in the URL. The OAuth 2.0 Security Best Current Practice deprecates it.
What is the state parameter for?
It ties the callback to the request the client started. This stops an attacker from making the client accept a code from a different authorization (a CSRF attack on the callback).
How long does an authorization code live?
RFC 6749 recommends a maximum of 10 minutes, and most providers use much less. A code can be redeemed only once. If someone tries to redeem it a second time, the server should revoke the tokens already issued for it.
Is the authorization code flow the same as OpenID Connect?
Not quite. OpenID Connect is built on top of this flow. It adds the openid scope and an ID token in the token response, so the app learns who signed in as well as getting an access token for the API.