salesforce oauth error: invalid_grant"

TL;DR

The authorization code is single-use and short-lived, so invalid_grant usually means the code was already redeemed, expired, or the token request does not match the original (redirect URI, client id). Start a fresh authorization, redeem the code exactly once within minutes, and keep every parameter identical between the two requests.

Error

{
  "error": "invalid_grant",
  "error_description": "expired authorization code"
}

Steps

1. Start a new authorization request and get a fresh code. Expected: a new single-use code.
2. Redeem it within a few minutes, exactly once. Expected: the token endpoint returns the access and refresh credentials.
3. Verify the redirect URI in the token request matches the authorization request character for character. Expected: mismatches are the most common avoidable cause.
4. Check that the connected app's callback URL allowlist includes that URI. Expected: the app accepts the redirect.
5. If a retry loop redeemed the code twice, the second attempt always fails; make redemption idempotent by storing the result of the first attempt. Expected: no double-redemption.

When to use

• The OAuth token exchange returns invalid_grant.
• An agent's auth flow worked once then fails on retry.
• After changing the connected app's callback URLs.

When not to use

• INVALID_LOGIN on password auth (different flow).
• Expired access tokens during a run (use the refresh flow, not a new code).

Tool compatibility

• Salesforce OAuth 2.0 web server flow; connected apps.
• Any OAuth client library.

Variant phrasings

expired authorization code

The code lived past its short lifetime; get a new one.

invalid_grant on token refresh

The refresh credential itself expired or was revoked; re-authorize.

Why it happens

Authorization codes are designed to be brief and single-use to limit theft. Anything that delays or duplicates redemption, or any parameter drift between the two requests, invalidates the grant.

Edge cases

• Load-balanced agents where two workers redeem the same code: the loser gets invalid_grant; coordinate or use separate flows.
• Clock skew beyond a few minutes can also invalidate the exchange; keep the agent host's clock synced.
• Revoking the refresh credential invalidates outstanding codes too.

Provenance

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