PKCE (Proof Key for Code Exchange)

What it means

PKCE, short for Proof Key for Code Exchange, is an extension to the OAuth authorization code flow defined in RFC 7636. It gives the client a one-time secret that it generates for each sign-in, so the authorization code that comes back through the browser is only useful to the client that asked for it. Three names cover the moving parts: code_verifier is the secret itself, code_challenge is the derived value the client sends up front, and S256 is the method used to derive it.

The gap it closes is the redirect. In the authorization code flow the code returns through the browser, and on a public client, such as a mobile or desktop app or a connector that cannot keep a client secret, another app could intercept that code and redeem it. PKCE does not encrypt anything and does not tell you who the user is. It binds the code to one sign-in attempt.

How it works

Before the authorization request, the client generates a random code_verifier and keeps it private. It hashes the verifier with SHA-256 and base64url-encodes the result to produce the code_challenge. The authorization request carries code_challenge and code_challenge_method set to S256, while the verifier stays on the client.

The user signs in and the client receives an authorization code. The client then sends that code to the token endpoint together with the original code_verifier. The server recomputes the challenge from the verifier and compares it with the value it stored from the first request. If they differ, the exchange fails. That is what happens to someone holding a stolen code: they have the code but not the verifier.

RFC 7636 also defines a plain method, where the verifier itself is sent as the challenge. S256 avoids putting the verifier on the front channel, which is why servers that care about the distinction ask for S256 specifically.

How OneLifeVibe uses it

OneLifeVibe requires PKCE with the S256 method for the account connector. The authorization request carries a code_challenge and code_challenge_method=S256, and the matching code_verifier goes with the request that redeems the authorization code. A missing or mismatched verifier means the exchange does not complete.

Meta Muse connects as the public client onelifevibe-muse, using PKCE and no client secret. That pairing is the point of a public client: it cannot hold a secret safely, so the per-sign-in verifier carries the proof instead. Generate a fresh verifier for each sign-in and treat the old one as disposable rather than reusing it or leaving it in shared configuration.

Common mistakes

Sending code_verifier in the authorization request is the most common error. The verifier belongs on the redemption request only; putting it on the front channel removes the protection you are trying to gain.

Reusing one verifier across sign-ins, or deriving the challenge with something other than SHA-256 and base64url, produces failures that look like bad credentials. Using the plain method where the server expects S256 fails the same way. Check the bytes you hash and the encoding you send before you debug anything else.

Finally, PKCE is not a replacement for validating redirect URIs or for client authentication where a client secret exists. It protects one step, the redemption of the authorization code.