Adamant Solutions

OAuth2 "invalid_grant": what it means and how to fix it

The server is saying: "I can see who you are (the client), but the grant you gave me (authorization code, refresh token, or credentials) is not acceptable." It is returned by the token endpoint as {"error":"invalid_grant"}, usually with HTTP 400. The same code covers many different causes, which is why it is so confusing. Answer the questions below to narrow it down.

Find your cause

All the causes and fixes

Authorization codes are single-use

  • A code can be exchanged only once; a second attempt returns invalid_grant (and some servers then revoke the tokens from the first exchange).
  • Guard the callback: handle it once, ignore reloads, and store a "code already used" flag.
  • Watch for both the server and the browser (or two tabs) processing the same callback.
  • Do not retry a failed token request with the same code: start the flow again.

The code expired

  • Authorization codes live very briefly (RFC 6749 recommends a maximum of 10 minutes; servers often use far less).
  • Exchange the code immediately in the callback handler, before doing anything slow.
  • Breakpoints in a debugger are a classic cause: the code expires while you step through.

The redirect_uri does not match the authorization request

  • If redirect_uri was sent in the authorization request, the token request must send exactly the same value (RFC 6749 section 4.1.3).
  • Differences as small as a trailing slash, http vs https, a port or letter case are enough.
  • Build the value in one place and reuse it. Compare the two strings with the redirect URI comparer.

The PKCE verifier does not match

  • The server hashes the code_verifier you send (S256) and compares it with the code_challenge from the authorization request; a mismatch is reported as invalid_grant (RFC 7636 section 4.6).
  • Generate the verifier once per login attempt and keep it until the exchange (session, or memory for a single-page app). Do not regenerate it on page load.
  • With several tabs, store the verifier by the state value so each flow finds its own.
  • Use method S256, not plain, and base64url without padding for the challenge. Our OAuth2 tester shows a verified example.

The grant belongs to another client

  • A code or refresh token is bound to the client it was issued to. Using another client_id (another app, tenant or environment) fails.
  • Check that the client_id and the token endpoint belong to the same environment as the authorization endpoint you used.

Refresh token rotation: an old token was reused

  • With rotation, every refresh returns a new refresh token and invalidates the old one. Using an old one again is treated as a possible theft and returns invalid_grant (and some servers revoke the whole token family).
  • Serialize refreshes: only one request may refresh at a time; the others must wait and use the new token.
  • Always store the new refresh token from every response, atomically.
  • A retry after a timeout can reuse a token the server already consumed: some servers allow a short grace period, many do not.

The refresh token is no longer valid

  • Refresh tokens expire (absolute or after inactivity) and are revoked on password change, sign-out, consent withdrawal or admin action.
  • Handle invalid_grant on refresh by sending the user through a new login, not by retrying.

Password grant: wrong credentials or not allowed

  • The username or password is wrong, the account is locked, or the user must change the password or complete MFA, which the password grant cannot do.
  • The password grant is removed from OAuth 2.1 and discouraged by the Security BCP: prefer authorization code with PKCE.

JWT bearer assertion rejected

  • Check iss, sub, aud (the token endpoint URL), exp (short lifetime), jti uniqueness and the signing key registered at the server.
  • Clock skew between your server and the authorization server is a frequent cause: synchronise with NTP.
  • Decode the assertion with the JWT inspector to check the claims.

Check the less common causes

  • Clock skew on either side (codes and assertions have validity windows).
  • A proxy or gateway that rewrites or caches the request or response.
  • The user or the application was disabled or removed between authorization and exchange.
  • Look at the authorization server log with the timestamp: most servers log the precise reason there, even when the response only says invalid_grant.

Frequently asked questions

Why does invalid_grant have so many causes?

RFC 6749 uses one error code for any problem with the grant itself: invalid, expired, revoked, used, issued to another client, or not matching the redirect URI. The precise reason is usually only in the server log.

Is invalid_grant a client bug or a server bug?

Almost always a client or flow issue: a code used twice, a changed redirect_uri, a wrong PKCE verifier or an old refresh token. Server bugs are rare.

Should I retry after invalid_grant?

No. Retrying with the same grant fails again. Restart the authorization flow (for codes) or ask the user to sign in again (for refresh tokens).

About this page

Nothing you select here is sent anywhere: the questions run in your browser. If you paste anything into the related tools, read their privacy notes and use test data. See the privacy notice.

Related: OAuth2 error doctor · OAuth2 flow tester · JWT inspector · All error guides

Still stuck, or designing the flow for your API?

We configure and review OAuth2/OIDC and API gateways, including WSO2 Identity Server and API Manager. See the WSO2 services or the security review.

Message us on LinkedIn