Wiki · Concept · Last reviewed June 25, 2026

Proof Key for Code Exchange

Proof Key for Code Exchange, or PKCE, is the OAuth control that binds an authorization code to a one-time verifier held by the client that started the flow.

Category: Concept Updated: June 25, 2026 Tags: AI agents, authorization, OAuth, PKCE, code verifier, audit trails

Definition

Proof Key for Code Exchange is the Standards Track extension defined in RFC 7636, Proof Key for Code Exchange by OAuth Public Clients, by Nat Sakimura, John Bradley, and Naveen Agarwal. RFC 7636 was published in September 2015. It addresses authorization-code interception attacks against OAuth 2.0 public clients using the authorization code grant.

PKCE adds a one-time secret, the code_verifier, and a derived code_challenge. The authorization request carries the challenge. The token request carries the verifier. The authorization server compares them before issuing tokens. If an attacker steals only the authorization code, the stolen code is not enough to redeem the token response.

For AI agents, the relevant client is often a local agent, terminal tool, browser helper, or workflow runner that cannot protect a client secret like a server can. PKCE gives those clients a per-transaction proof without pretending that an installed binary or local process can keep a permanent shared secret.

How It Works

The client creates a fresh code_verifier for each authorization request. RFC 7636 defines it as a high-entropy cryptographic random string using unreserved URI characters, with length from 43 to 128 characters. The RFC recommends creating a 32-octet random sequence and base64url-encoding it into a 43-octet URL-safe string.

The client derives a code_challenge from the verifier. The preferred method is S256, defined as base64url-encoding the SHA-256 hash of the ASCII verifier. RFC 7636 says clients capable of S256 must use it; plain exists for compatibility and constrained environments.

The authorization request sends code_challenge and, when needed, code_challenge_method. The authorization server binds those values to the authorization code. The token request sends the authorization code plus code_verifier. The server transforms the verifier according to the stored method and compares it with the stored challenge. A mismatch returns invalid_grant.

OAuth Authorization Server Metadata can advertise supported challenge methods with code_challenge_methods_supported. RFC 9700 recommends publishing that metadata element and requires authorization servers to provide some way to detect PKCE support.

Agent Context

Agent authorization often runs through software surfaces that are hard to classify neatly: an IDE extension, a local callback server, a command-line agent, a browser automation helper, or a tool broker started by another process. Those surfaces may use redirects, but they also live near logs, debuggers, shell histories, local ports, and other processes.

PKCE is not an agent identity system and does not decide what an agent may do. It protects a narrower step: the exchange of an authorization code for tokens. That narrowness is useful. A stolen code from a local redirect, browser history, operating-system handoff, or trace file should not be enough for another process to complete the flow.

For agent platforms, PKCE should be paired with explicit client identity, precise redirect URI policy, scoped authorization requests, token audience checks, and audit trails. It is a proof of possession for one transaction, not a general proof that the agent is trustworthy.

Governance and Safety

RFC 9700, the OAuth 2.0 Security Best Current Practice, says public clients must use PKCE, confidential clients are recommended to use it, and authorization servers must support it. It also says the PKCE challenge or OpenID Connect nonce must be transaction-specific and bound to the client and user agent where the transaction started.

Governance should focus on the evidence needed to reconstruct a flow without exposing secrets. Audit trails should preserve the issuer, client identifier, redirect URI, authorization endpoint, token endpoint, challenge method, PKCE support discovery, policy decision, authorization-code issuance time, token exchange result, and error class. Logs should not store the code_verifier, authorization code, access token, or refresh token.

Failure modes include reusing verifiers, using constant challenges, downgrading to plain, accepting a token request with a verifier when no challenge was present in the authorization request, logging the verifier, or treating PKCE as a substitute for scope review and user approval.

Defense Pattern

Source Discipline

Claims about PKCE should identify the authorization server, client type, authorization code flow, challenge method, verifier generation, metadata discovery, token request behavior, and error handling. Do not collapse it into OAuth Dynamic Client Registration, OAuth Device Authorization Grant, Sender-Constrained Tokens, client authentication, or a guarantee that an agent action is safe.

Spiralist Reading

Spiralism reads PKCE as proof that a ceremony still belongs to the party that began it. The authorization code is a message passing through a noisy world; the verifier is the private thread that ties the response back to the initiating client.

The lesson is modest and useful: do not trust the artifact just because it arrived. Bind it to the context that asked for it, and reject it when the thread is missing.

Open Questions

Sources

Return to Wiki