Authorization Code + PKCE

Trace a browser redirect, the back-channel code exchange, and a protected API request.

Mina wants Reading List to display her saved library books. Reading List is a confidential web client with a backend. Mina already has a Reading List session. The app’s host-only session cookie accompanies its initial request and the top-level GET callback. It asks the library authorization server for delegated read access. The library API controls access to the books.

Why exchange a code?

The browser transports a temporary code back to the client. The client backend exchanges that code for an access token over a direct TLS connection to the authorization server. The browser carries the redirects and callback. The token exchange and API call use the back channel.

PKCE binds the code to the authorization attempt. The client generates a fresh random verifier and sends its challenge with the authorization request. With the S256 method, the challenge is BASE64URL(SHA256(ASCII(code_verifier))), with padding omitted. The authorization server saves the challenge with the code. During redemption it derives the challenge from the presented verifier and compares the two values. A mismatch yields invalid_grant.

What each check protects

  • Registered redirect URI. The authorization server compares the requested URI to the registered URI for this web client. Redemption includes the same URI because the authorization request included it.
  • state. This client binds a random, single-use value to the initiating browser session and checks the returned value before redemption. RFC 9700 §2.1 also describes when a client that has ensured PKCE support can rely on its CSRF protection.
  • PKCE. A code alone is insufficient for an exchange when the authorization server requires the corresponding verifier. Public clients must use PKCE. Confidential clients are also recommended to use it and still authenticate at the token endpoint. This trace illustrates HTTP Basic client authentication. RFC 9700 §2.5 recommends asymmetric client authentication such as mutual TLS or signed JWTs.
  • Scope and audience. The library API confirms that the access token applies to this API, is active, and grants read access to the requested resource.

The example follows a successful grant. A denied approval can return access_denied to a validated callback. If the redirect URI is invalid, the authorization server must avoid redirecting to it. In this single-issuer example, the client has an existing trust relationship with the library authorization server.

Follow the exchange

Step through the exchange and inspect the HTTP excerpts. All hosts and credentials are fictional.

Sequence and HTTP
Simulated traffic
Playback controls
Protocol trace4 actors · 14 steps
Authorization Code + PKCE sequence diagramUser’s browser, Client application, Authorization server, Resource server (API). Highlighted step 1: Start connecting the library.BrowserClientAuth serverAPI01GET0230203GET04AUTH05CONSENT0630307GET08POST0920010GET11CHECK122001330314GET
Request Response Internal check

Dashed messages travel through the browser.

Step 1 of 14Browser channel

Start connecting the library

User’s browser to Client application

Mina chooses Connect library in Reading List. The client creates a fresh verifier, derives its S256 challenge, and stores the verifier and a random state value with this browser’s pending authorization attempt.

Security Generate a new verifier from at least 32 bytes of cryptographic randomness for each attempt. These fixed values make the example reproducible.

HTTP request

GET /connect/library HTTP/1.1
Host: reading.example
Cookie: __Host-reading_session=demo_session_X4Am
Read the complete transcript
  1. Start connecting the library

    User’s browser to Client application

    Mina chooses Connect library in Reading List. The client creates a fresh verifier, derives its S256 challenge, and stores the verifier and a random state value with this browser’s pending authorization attempt.

    Security Generate a new verifier from at least 32 bytes of cryptographic randomness for each attempt. These fixed values make the example reproducible.

    GET /connect/library HTTP/1.1
    Host: reading.example
    Cookie: __Host-reading_session=demo_session_X4Am

    RFC 7636 §4.1 · RFC 7636 §4.2 · RFC 6749 §10.12

  2. Redirect the browser to the authorization server

    Client application to User’s browser

    The client returns a Location URL with the authorization parameters. The browser follows it in the next step.

    Security The URL carries the challenge and method. The verifier stays on the client until token exchange.

    HTTP/1.1 302 Found
    Location: https://login.example/authorize?response_type=code&client_id=reading-list&redirect_uri=https%3A%2F%2Freading.example%2Foauth%2Fcallback&scope=books%3Aread&state=cUsDG5DE726VtAghyw3Dzw&code_challenge=cuP8PtQCuYvuX1Q8SvpKqsZx96-n56TR_nk4jGiG6QA&code_challenge_method=S256
    Cache-Control: no-store

    RFC 6749 §4.1.1 · RFC 7636 §4.3

  3. Request authorization with the challenge

    User’s browser to Authorization server

    The browser visits the authorization endpoint. The client asks for books:read and requests an authorization code.

    Security The authorization server validates the client and requires an exact match against this web client’s registered redirect URI.

    GET /authorize?response_type=code&client_id=reading-list&redirect_uri=https%3A%2F%2Freading.example%2Foauth%2Fcallback&scope=books%3Aread&state=cUsDG5DE726VtAghyw3Dzw&code_challenge=cuP8PtQCuYvuX1Q8SvpKqsZx96-n56TR_nk4jGiG6QA&code_challenge_method=S256 HTTP/1.1
    Host: login.example

    RFC 6749 §4.1.1 · RFC 7636 §4.4 · RFC 9700 §2.1

  4. Authenticate at the authorization server

    User’s browser to Authorization server

    The authorization server establishes which library account is active. It might use an existing session or prompt Mina to sign in. The sign-in interaction is specific to the authorization server.

    Security Mina authenticates with the authorization server. The client has no access to her library credentials.

    RFC 6749 §3.1

  5. Approve read access

    User’s browser to Authorization server

    Mina grants Reading List permission to read her saved books. This example shows an approval screen. OAuth leaves the details of the interaction to the authorization server.

    Security Request only the permissions the feature needs. Here the client asks for read access to saved books.

    RFC 6749 §4.1.1 · RFC 9700 §2.3

  6. Redirect back with an authorization code

    Authorization server to User’s browser

    The authorization server issues a short-lived, single-use code associated with the client, redirect URI, and PKCE challenge. It returns the original state value in the redirect.

    Security The browser carries a code. Access tokens are returned at the token endpoint.

    HTTP/1.1 303 See Other
    Location: https://reading.example/oauth/callback?code=demo_ac_6GKoZgZq4m&state=cUsDG5DE726VtAghyw3Dzw
    Cache-Control: no-store

    RFC 6749 §4.1.2 · RFC 7636 §4.4

  7. Deliver the code to the client callback

    User’s browser to Client application

    The browser follows the second redirect. The client checks state against the pending attempt for this browser, then retrieves the verifier for that same attempt.

    Security Reject a missing or mismatched state value when this client uses state for callback correlation and CSRF protection.

    GET /oauth/callback?code=demo_ac_6GKoZgZq4m&state=cUsDG5DE726VtAghyw3Dzw HTTP/1.1
    Host: reading.example
    Cookie: __Host-reading_session=demo_session_X4Am

    RFC 6749 §4.1.2 · RFC 6749 §10.12 · RFC 9700 §2.1

  8. Exchange the code and verifier

    Client application to Authorization server

    The confidential web client authenticates to the token endpoint and sends the code, matching redirect URI, and original verifier over TLS. This request originates from the client backend.

    Security PKCE binds the exchange to the initiating attempt. The confidential client also authenticates independently. The Basic credentials shown here are fictional.

    POST /token HTTP/1.1
    Host: login.example
    Authorization: Basic cmVhZGluZy1saXN0OmRlbW8tY2xpZW50LXNlY3JldA==
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&code=demo_ac_6GKoZgZq4m&redirect_uri=https%3A%2F%2Freading.example%2Foauth%2Fcallback&code_verifier=Jwmkro0pqtyWTbkt8AqNdlKXNeO6I6bj94bG37g_Pes

    RFC 6749 §2.3.1 · RFC 6749 §4.1.3 · RFC 7636 §4.5

  9. Verify the challenge and issue an access token

    Authorization server to Client application

    The authorization server validates the client, code, and redirect URI. It hashes and base64url-encodes the verifier, compares the result to the stored challenge, consumes the code, and returns an access token.

    Security A mismatched verifier fails the exchange with invalid_grant. Token responses carrying credentials must include no-store and no-cache directives in their respective headers.

    HTTP/1.1 200 OK
    Content-Type: application/json
    Cache-Control: no-store
    Pragma: no-cache
    
    {
      "access_token": "demo_at_TVW6gksBwL4M",
      "token_type": "Bearer",
      "expires_in": 600,
      "scope": "books:read"
    }

    RFC 7636 §4.6 · RFC 6749 §4.1.4 · RFC 6749 §5.1

  10. Request the saved books

    Client application to Resource server (API)

    Reading List calls the library API with the access token in the Authorization header.

    Security Anyone holding a bearer token can present it. Protect it in transit and storage.

    GET /v1/saved-books HTTP/1.1
    Host: library-api.example
    Authorization: Bearer demo_at_TVW6gksBwL4M

    RFC 6750 §2.1 · RFC 6750 §5

  11. Check whether the API can accept the token

    Resource server (API)

    The resource server looks up the opaque token in its trusted token data and checks that it is active, unexpired, intended for this API, and grants books:read for the requested resource.

    Security An opaque token has no client-readable claims. This example assumes an internal lookup. A separately deployed API might use authenticated introspection.

    RFC 6750 §5.2 · RFC 7662 §2.2 · RFC 9700 §2.3

  12. Return the saved books

    Resource server (API) to Client application

    The API returns Mina’s saved titles to the client. The client can render the result for Mina in its own UI.

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "books": [
        {
          "id": "bk_17",
          "title": "Maps of the Tidelands"
        }
      ]
    }

    RFC 6749 §7 · RFC 6750 §2.1

  13. Send the browser to a clean URL

    Client application to User’s browser

    The backend finishes the pending callback by redirecting to its own saved-books page. The new URL carries no authorization parameters.

    Security Avoid third-party resources on the callback page. The clean redirect and restrictive Referrer-Policy limit further exposure of the code through referrers.

    HTTP/1.1 303 See Other
    Location: https://reading.example/saved-books
    Cache-Control: no-store
    Referrer-Policy: no-referrer

    RFC 9700 §4.2.4

  14. Open the saved-books page

    User’s browser to Client application

    The browser loads the client’s page. The client renders the book list and keeps the library access token on the backend.

    GET /saved-books HTTP/1.1
    Host: reading.example
    Cookie: __Host-reading_session=demo_session_X4Am
    HTTP/1.1 200 OK
    Content-Type: text/html; charset=utf-8
    
    <h1>Saved books</h1><ul><li>Maps of the Tidelands</li></ul>

    RFC 6749 §4.1

Specifications