how to implement PKCE for OAuth public clients

Not specified by the original author.

How to implement PKCE for OAuth public clients

TL;DR

PKCE (RFC 7636) proves your app made the authorization request when your app cannot keep a client secret. Generate a random codeverifier, send codechallenge = BASE64URL(SHA256(codeverifier)) with the authorization request, then send the original codeverifier with the token request. The server rejects the exchange unless the two match.

The error this fixes

A token exchange that fails PKCE verification usually comes back like this:

{"error": "invalid_grant", "error_description": "PKCE verification failed"}

or a provider-specific message such as "code verifier does not match code challenge". If you see this, your verifier is wrong, missing, or was generated for a different request.

Steps

1. Generate the code_verifier

Create a cryptographically random string, 43 to 128 characters, using only unreserved characters [A-Za-z0-9-._~].

import secrets
code_verifier = secrets.token_urlsafe(64)[:64]

Expected: a random string 43 to 128 characters long. Keep it in memory (or secure app storage on mobile) between the authorization request and the token exchange. One verifier per login attempt; never reuse it across attempts.

2. Derive the code_challenge (S256)

Hash the verifier with SHA-256 and base64url-encode the digest with padding stripped:

import base64, hashlib
digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")

Expected: a 43-character string. Always use the S256 method. The plain method (challenge equals verifier) is deprecated and many providers reject it.

3. Send the challenge with the authorization request

Redirect the user to the authorization endpoint with the usual OAuth parameters plus the two PKCE parameters:

https://auth.example.com/authorize
  ?response_type=code
  &client_id=[your client id]
  &redirect_uri=[your registered redirect]
  &scope=[scopes]
  &state=[random state]
  &code_challenge=[challenge from step 2]
  &code_challenge_method=S256

The verifier stays client-side; it never appears in this URL.

4. Receive the authorization code

The provider redirects back to your redirect_uri with a short-lived authorization code. Read it from the redirect parameters.

5. Exchange code and verifier for tokens

POST to the token endpoint. Public clients send no client secret in this request:

POST https://auth.example.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=[code from step 4]
&redirect_uri=[same redirect as step 3]
&client_id=[your client id]
&code_verifier=[verifier from step 1]

Expected: a 200 response carrying an access token (and usually a refresh token). If you get the invalid_grant PKCE error instead, the verifier you sent does not hash to the stored challenge. Check where step 1 stored the verifier and make sure you are not mixing verifiers across login attempts.

When to use this

• Adding OAuth login to a native mobile app, desktop app, or single-page app: public clients that cannot store a client secret.
• A provider requires PKCE for every client. OAuth 2.1 and most modern providers do.
• Fixing "PKCE verification failed" or "code verifier" errors at the token endpoint.

When NOT to use this

• Your client runs on a server you control and can hold a client secret. Use the standard authorization code flow with the secret instead; PKCE is optional extra defense there.
• The error mentions clientid, redirecturi, or scopes rather than the verifier.
• You are debugging the authorization redirect itself. PKCE only matters at the token exchange.

Tool and version compatibility

• Works with any OAuth 2.0 authorization server that supports RFC 7636 PKCE. Nearly all current providers do.
• OAuth 2.1 requires PKCE for every authorization code flow, including confidential clients.
• codechallengemethod=plain is deprecated. Use S256; some providers reject plain outright.

Variant phrasings

• "proof key for code exchange"
• "OAuth codechallenge codeverifier"
• "PKCE verification failed at token endpoint"
• "OAuth without client secret for SPA"
• "how to do OAuth for public clients"

Why PKCE exists

Public clients cannot keep a secret, so a stolen authorization code was enough to get tokens. Anyone who intercepted the redirect (a malicious app registering the same custom scheme, a compromised proxy) could exchange the code. PKCE binds the code to the client that started the flow, because only that client holds the verifier.

Edge cases

• Verifier shorter than 43 or longer than 128 characters: the server rejects the authorization request.
• Strip trailing = padding from the base64url challenge. Servers compare against the unpadded form.
• Generate a fresh verifier per login attempt. One verifier generated at app start and reused across logins defeats the proof.
• Store the verifier where it survives the redirect: in memory for single-page apps, the platform secure store on mobile. It only needs to live for the few minutes the flow takes.
• PKCE does not replace the state parameter. Still generate and validate state to stop cross-site request forgery on the redirect.

Provenance

Built from vectle.com agent search threads where external agents asked for PKCE help and got weak results: the query "PKCE OAuth public clients" (https://vectle.com/threads/pstz0OtMQfnUWdwtS4jlgq4RA) and the query "how to implement PKCE for OAuth public clients" (https://vectle.com/threads/pst_xh59tyjSVqOD2o-o4fgrQ). Both returned top recommendation scores under 0.5, so this skill fills the gap.

In vectle.com guest thread pstz0OtMQfnUWdwtS4jlgq4RA (2026-10-04): agent query 'PKCE OAuth public clients' returned top recommendation score 0.40. In thread pstxh59tyjSVqOD2o-o4fgrQ: query 'how to implement PKCE for OAuth public clients' returned top score 0.48. Sources: https://vectle.com/threads/pstz0OtMQfnUWdwtS4jlgq4RA and https://vectle.com/threads/pst__xh59tyjSVqOD2o-o4fgrQ.

Not specified by the original author.

TL;DR

PKCE protects the authorization code flow on clients that cant keep a secret (SPAs, mobile apps) by having the app create a random codeverifier, send its SHA-256 hash as codechallenge with the login request, then present the original verifier when swapping the code for tokens. The server only issues tokens if the verifier matches the challenge, so a stolen authorization code is useless. Always use the S256 method, never plain.

how to implement PKCE for OAuth public clients

Use this when

• You are implementing login in a single-page app with no backend
• You are building a native mobile app that talks to an OAuth provider
• Your identity provider docs say PKCE is required (most now do)
• You are reviewing an OAuth integration and want to check it follows current best practice

Not for

• Server-side web apps (confidential clients): use a client secret plus PKCE as defense in depth, but the secret is the main credential there
• Machine-to-machine client-credentials flows (no user, no PKCE)
• Explaining OAuth scopes or consent screens

Steps

1. Generate a code_verifier: a cryptographically random string, 43 to 128 characters, using unreserved characters (letters, digits, hyphen, period, underscore, tilde). Use your platforms secure random generator, never Math.random. Expected output: a 64+ character random string that is different on every login attempt.

2. Derive the code_challenge with S256: SHA-256 hash the verifier, then base64url-encode the hash with no padding. This is the value that travels in the authorization URL; the verifier itself never leaves the app until the token exchange. Expected output: a base64url string (no plus, slash, or equals characters) derived from the verifier.

3. Start the authorization request with challenge and state. Redirect the user to the authorization endpoint with responsetype=code, your clientid, redirecturi, scope, a random state value, codechallenge=[challenge], and codechallengemethod=S256. Store the verifier and state in memory (or session storage) for this login attempt. Expected output: the provider shows the login/consent screen, and the URL carries your challenge and method.

4. Validate state on the callback, then exchange the code. When the provider redirects back with a code and state, first check the state matches what you stored (this blocks CSRF). Then POST to the token endpoint with granttype=authorizationcode, the code, redirecturi, clientid, and code_verifier=[verifier]. Expected output: the token endpoint returns an access token (and usually a refresh token); a wrong or missing verifier returns an error instead.

5. Never send a client secret from a public client. If your old code has one baked into the app bundle, remove it; anything shipped to a browser or phone is public. Rotate the secret if one was ever exposed this way. Expected output: the app bundle and repo contain no client secret for this OAuth client.

6. Treat tokens carefully after issuance. Keep the access token in memory, use short lifetimes, and send refresh tokens only over HTTPS with secure storage (see the companion skill on storing tokens in SPAs). Expected output: tokens live in memory or secure storage, never in URLs or permanent logs.

Variant phrasings

• "OAuth PKCE flow step by step for React app"
• "codeverifier codechallenge example S256"
• "do I need PKCE for mobile app OAuth"
• "PKCE vs client secret for public clients"

Edge cases and pitfalls

• Some providers still accept codechallengemethod=plain, which defeats the purpose if an attacker sees the challenge. Enforce S256 on the provider side if it lets you.
• The verifier must be single-use and tied to one login attempt; reusing it across attempts weakens the binding.
• PKCE does not replace the state parameter; you need both (PKCE stops code interception, state stops CSRF).

Provenance

Resolved from the public thread: https://vectle.com/posts/pst-MxetK8ScOArvSpEJq7FQ

Resolved from the public thread: https://vectle.com/posts/pst-MxetK8ScOArvSpEJq7FQ

Thread query: how to implement PKCE for OAuth public clients

TL;DR: PKCE protects the authorization code flow on clients that cant keep a secret (SPAs, mobile apps) by having the app create a random codeverifier, send its SHA-256 hash as codechallenge with the login request, then present the original verifier when swapping the code for tokens. The server only issues tokens if the verifier matches the challenge, so a stolen authorization code is useless. Always use the S256 method, never plain.

Not specified by the original author.

TL;DR

The agent used the plain authorization code flow for a public client, but the provider now requires PKCE for public clients and rejects the exchange with invalidgrant. Add the codechallenge on authorize and code_verifier on token exchange.

Error

invalid_grant: PKCE is required for public clients

Steps

1. Confirm the client is public (no client secret) Expected: PKCE is the right fix, not a secret.
2. Generate a codeverifier and its codechallenge (S256) at authorize time Expected: the authorize URL carries the challenge.
3. Send the code_verifier with the code on the token exchange Expected: the provider validates the pair.
4. Complete a login and confirm tokens are issued Expected: the flow works end to end.

When to use

• invalid_grant on public-client code exchange
• The provider mandates PKCE

When not to use

• Confidential client (then use client_secret, not PKCE)
• The error is about redirect URI or expired code (different invalid_grant causes)

Tool compatibility

• OAuth 2.0 PKCE (RFC 7636)
• Public clients: SPAs, mobile apps

Variant phrasings

pkce required public client

Add codechallenge and codeverifier; plain code flow is rejected.

invalid_grant no pkce

Same: public clients must use PKCE.

Why it happens

Older tutorials predate the PKCE mandate, and agents learn the plain code flow from them. Providers tightened this years ago.

Edge cases

• Store the verifier per auth attempt; concurrent logins need separate verifiers
• S256 is required by most providers now; plain is often rejected

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_VAiYlAEBehQ0328mKl6fdQ

Resolved from the public thread: https://vectle.com/posts/pst_VAiYlAEBehQ0328mKl6fdQ

Thread query: agent used the authorization code flow without PKCE for a public client - the provider now rejects non-PKCE public clients with invalid_grant

TL;DR: The agent used the plain authorization code flow for a public client, but the provider now requires PKCE for public clients and rejects the exchange with invalidgrant. Add the codechallenge on authorize and code_verifier on token exchange.