OAuth/OIDC Debugger

Debug an OAuth 2.0 or OIDC flow: tokens, PKCE, redirect URIs and error codes

OAuth failures are frustrating because the error you get back is deliberately vague. invalid_grant covers at least four unrelated mistakes. A redirect URI mismatch is a single invisible character. A token that "does not work" is often a perfectly valid token with the wrong aud. This tool gives you five workbenches for those specific problems, all running in your browser.

What it does not do: it does not run a live OAuth flow. It does not hold client secrets, exchange authorization codes, call token endpoints, or host a callback. It builds requests and inspects artefacts — you paste tokens in and copy URLs out, and the network calls stay with your own application and your identity provider. Nothing you paste is transmitted anywhere.

The five tabs

Authorization code with PKCE is the answer to "which flow"

If you are choosing a flow today, the choice is essentially made for you. Authorization code flow with PKCE is the current default for every client type — single-page apps, mobile apps, and confidential server-side apps alike. The Flow Tester offers it first for that reason.

The plain authorization code flow is still correct for a confidential client that can keep a secret on a server, and it is offered here, but adding PKCE costs nothing and closes a real attack. Implicit flow is included and marked deprecated: it returns tokens directly in the URL fragment, which puts them in browser history, referrer headers and logs, with no way to authenticate the client at redemption. If you are still on it, migrating is the work.

PKCE (RFC 7636) exists because a public client cannot hold a secret. Anyone who intercepts the authorization code — through a hijacked custom URL scheme on mobile, a malicious app registered for the same scheme, or a leaky redirect — could otherwise redeem it. PKCE binds the code to the specific client instance that started the flow:

• Before redirecting, the client generates a random code verifier.
• It sends code_challenge = base64url(SHA-256(verifier)) and code_challenge_method=S256 on the authorization request.
• The authorization server stores the challenge alongside the issued code.
• At the token endpoint, the client presents the original verifier. The server hashes it and compares.

An intercepted code is useless without the verifier, which never left the client. The generator here produces the verifier from 32 bytes of crypto.getRandomValues — the browser's cryptographic random source, not Math.random — and base64url-encodes it, giving a 43-character verifier. The challenge is computed with the Web Crypto SHA-256 implementation. There is a plain option for providers that do not support S256; it is marked as weaker because plain sends the verifier itself as the challenge, which an interceptor of the authorization request can simply read.

The verifier must be 43 to 128 characters using only A-Z a-z 0-9 - . _ ~. If you generate your own and hit "the code_verifier is invalid", check the length and the character set first — standard base64 output containing +, / or = is the usual culprit, which is why base64url encoding is required.

Access token, ID token, refresh token

Conflating these causes more OIDC bugs than anything else, so be precise:

Three rules that follow from that table and prevent most of the damage:

• Never send an ID token to an API as authorization. Its audience is your client. An API that accepts it is accepting a token minted for someone else's audience, which is precisely the check that stops token substitution attacks.
• Never treat an ID token as a session. It says a login happened at a point in time. Exchange it for your own session and stop re-reading it.
• Do not parse access tokens in your client. They are opaque by contract even when they happen to decode as JWTs today. A provider can change the format without notice and your client will break. Read user data from the ID token or the userinfo endpoint.

Reading the claims

Paste a token into the decoder and it splits on the dots, base64url-decodes the header and payload, and shows both as formatted JSON along with the raw signature segment. Timestamp claims are rendered as ISO dates plus a relative phrase — "expired 14 minutes ago", "expires in 3 hours" — because reading Unix seconds by eye is where mistakes happen.

The claims worth checking, in the order they usually break things:

• aud — the intended recipient. If your API rejects a token that looks fine, compare this against the identifier the API expects, character for character.
• iss — the issuer. Must exactly match the expected issuer string, including trailing-slash presence and tenant path. Multi-tenant providers vary the issuer per tenant and this catches people out.
• exp, nbf, iat — expiry, not-before, issued-at, all in Unix seconds.
• sub — the stable user identifier. Key your user records on this, not on email, which changes.
• scope or scp — the granted scopes, which may be fewer than you asked for.
• nonce — on an ID token, must match the nonce you sent on the authorization request.
• alg and kid in the header — the signing algorithm and which key from the provider's JWKS signed it.

The decoder flags a missing alg, an alg of none (the classic signature-stripping vulnerability, and never legitimate in a real deployment), a token already past exp, a token not yet valid per nbf, a missing exp entirely, and a lifetime longer than a year.

It does not verify the signature, and this is deliberate rather than a shortcoming to work around: verification requires the shared secret for HMAC algorithms or the issuer's public key for RSA and ECDSA, and pasting a production signing secret into a web page is not something you should do anywhere. Decoding tells you what a token claims. Only your backend, fetching the provider's JWKS and validating against it, tells you whether the token is genuine. Treat everything you read here as unverified input.

redirect_uri mismatch

The most common OAuth failure, and the least informative error. Providers match redirect URIs by exact string comparison — no normalisation, no wildcards, no leniency — because any flexibility here becomes an open-redirect vulnerability that leaks authorization codes.

The validator takes what you registered and what you actually sent and diffs them component by component: scheme, host, port, path, query and fragment. Ports are normalised to their scheme defaults so https://x.com and https://x.com:443 compare as equal, which is how providers generally treat them. Everything else is compared literally.

What it catches, in rough order of frequency:

• A trailing slash. /callback and /callback/ are different URIs. Flagged explicitly because it is invisible when you read it.
• http versus https. Often a dev registration used against a staging deployment that terminates TLS.
• A port that appears on one side only, typically a dev server on 3000 or 5173.
• Path case. /Callback is not /callback.
• A query string on one side. Some providers reject any query parameters on a redirect URI outright.
• www or a subdomain difference between the registration and the deployed host.

Two things to know beyond the diff. First, redirect_uri must be identical on the authorization request and the token request — sending it correctly on the first and omitting or altering it on the second produces invalid_grant at the token endpoint, which sends people hunting in entirely the wrong place. Second, register every environment's URI up front. Adding one at 2am during an incident means waiting on a console you may not have access to.

invalid_grant, and the other codes

The error debugger holds the standard OAuth 2.0 error codes with their HTTP status, their probable causes ranked by likelihood, and concrete fixes. invalid_grant deserves calling out because it is the most overloaded:

• The code expired. Authorization codes are short-lived — on the order of minutes. A code that sat in a debugger while you inspected it is dead by the time you send it.
• The code was already used. Single-use, always. React strict mode double-invoking an effect, a retried request, or a user refreshing the callback page will burn it and the second attempt fails.
• redirect_uri differs between the authorization request and the token request, as above.
• The refresh token was revoked or rotated. With rotation enabled, using an old refresh token after a newer one was issued is treated as replay, and providers commonly revoke the whole chain in response.

Also covered: invalid_client (credentials or the wrong client authentication method — HTTP Basic versus form post is a frequent silent mismatch), invalid_request, unauthorized_client (grant type not enabled for that client), access_denied (the user pressed cancel — handle it as a normal path, not an error page), unsupported_response_type, and invalid_scope.

Scope is not audience

These get confused constantly and the symptom is a 403 from an API against a token that decodes perfectly.

Scope is what the client asked permission to do: openid profile email, read:orders. It is a space-separated list on the authorization request, and the user may consent to a subset. Audience is which resource the resulting token is for. Many providers will happily issue you a token with all the scopes you requested and an audience pointing at their own userinfo endpoint rather than your API, unless you explicitly ask for your API — via an audience or resource parameter, or by using scopes prefixed with the API's identifier, depending on the provider.

The diagnostic is direct: decode the access token and look at aud. If it is not your API's identifier, no amount of scope tuning will help. Add the audience parameter to the authorization request in the Flow Tester and try again.

Related: requesting a scope the client is not authorised for yields invalid_scope, and requesting one the user declines yields a token with fewer scopes than you asked for and no error at all. Always read the granted scope claim back rather than assuming you got what you requested.

Clock skew

Token validation is time-based, so a wrong clock breaks it in ways that look like anything but a clock problem. A validator rejects a token as expired when exp is in its past, or as not-yet-valid when nbf is in its future. If your server's clock runs a couple of minutes ahead of the identity provider's, freshly issued tokens are "expired" on arrival.

• Symptom to recognise: intermittent or total 401s with a valid-looking token, often on one host in a pool and not others.
• Standard practice is a small leeway — commonly a minute or two — when comparing exp, nbf and iat. Most JWT libraries expose this; use it rather than widening token lifetimes.
• Fix the underlying cause with NTP on every host that validates tokens, including containers and CI runners.
• Note that this decoder evaluates expiry against your own device's clock. If your laptop clock is wrong, its expiry verdict will be wrong too — a useful thing to rule out before you go looking at the provider.

A working order for debugging

• Build the authorization URL in the Flow Tester with the parameters your app actually sends. If the provider rejects it, the problem is in the request, before any code exists.
• If you get redirected back with an error, run the two redirect URIs through the validator before anything else.
• If you got a code but the token exchange fails, look up the exact error code — and check that the redirect URI is identical on both requests.
• If you got tokens but the API refuses them, decode the access token and read aud, iss, exp and scope, in that order.
• If everything decodes correctly and it still fails, compare your clock against the issuer's, then check the signature on your backend against the provider's JWKS.