GeekCoding101 make your way to geek

OAuth 2.0 Authorization Code Flow with PKCE, Step by Step

How the OAuth 2.0 authorization code flow works: every redirect and request with PKCE, why you get a code, not a token, and the checks that keep it safe.

7 min read
Oauth 2.0 Authorization Code Flow
On this pageThe flow at a glance

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

  1. Redirect to the authorization server. The client sends the user’s browser to the authorization endpoint.
  2. Sign-in and consent. The user authenticates on the authorization server’s own pages and approves the requested access.
  3. Code returned. The authorization server redirects the browser back to the client with an authorization code.
  4. Code exchanged for tokens. The client sends the code to the token endpoint over a direct back-channel request.
  5. 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

ItemChannelWho sees it
Authorization request (client_id, scope, state, code_challenge)Front channel (browser redirect)Browser, client, authorization server
User’s passwordAuthorization server’s pages onlyUser and authorization server, never the client
Authorization codeFront channel (redirect back)Browser, client
code_verifier, client secretBack channel (direct POST)Client and authorization server
Access token, refresh tokenBack 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.1
Host: auth.example.com

code_challenge is BASE64URL(SHA256(code_verifier)). The verifier itself never leaves the client at this stage.

ParameterPurpose
response_type=codeAsks for an authorization code (this is what makes it the code flow)
client_idIdentifies the registered client
redirect_uriWhere the server sends the browser back; must match a registered value
scopeThe access being requested
stateRandom value that ties the callback to this request
code_challenge / code_challenge_methodPKCE: 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 Found
Location: https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

Before 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.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic bXktYXBwOm15LXNlY3JldA==
grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

The 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.

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 openid scope and an ID token added.

Common Mistakes to Avoid

  • Skipping the state check. 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. Use S256; plain sends 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.

Thanks for reading my blog post! Feel free to check out my other posts or contact me via the social links in the footer.

Keep reading

All posts