googleapis Node client does not auto-refresh the access token ("Invalid Client" after expiry)u0026type=skill

Not specified by the original author.

TL;DR

For "forceRefreshOnFailure": i sign in, get tokens, and set them on the OAuth2 client with setCredentials. API calls work until the access token expires, then instead of auto-refreshing I get an "Invalid Client" error. The refresh token is valid (set immediately before each request). The fix users verified: only pass the refresh token, not the access token (the access token is not meant to be stored anyway).

forceRefreshOnFailure

When to use

You are seeing this: I am using googleapis 59.0.0 on Node. Use this skill when you run into "googleapis Node client does not auto-refresh the access token ("Invalid Client" after expiry)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: googleapis 59.0.0. If you are on something much newer or older, the details may have shifted.

What's going on

I am using googleapis 59.0.0 on Node. I sign in, get tokens, and set them on the OAuth2 client with setCredentials. API calls work until the access token expires, then instead of auto-refreshing I get an "Invalid Client" error. The refresh token is valid (set immediately before each request). What step am I missing to get automatic refresh working?

The verified fix

The trap is passing the access token to setCredentials. When the access token is bound to the client, the library does not refresh properly on expiry. The fix users verified: only pass the refresh token, not the access token (the access token is not meant to be stored anyway). Like this: call setCredentials with the refresh value and leave the short-lived access value out of the object. Alternatively, set the forceRefreshOnFailure client option , a user confirmed that also fixed it for them. Several people hit this and the refresh-token-only pattern is the one Google documents for long-lived flows.

How to use this

Take the question above and check if it matches what you're seeing. If it does, work through the verified fix step by step. Start with the cause described first, because that's what tells you the fix applies to your setup, then apply the changes in the order given. Verify by re-running whatever failed before, and expect the same behavior the thread author reported.

Someone asked: I am using googleapis 59.0.0 on Node. I sign in, get tokens, and set them on the OAuth2 client with setCredentials. API calls work until the access token expires, then instead of auto-refreshing I get an "Invalid Client" error. The refresh token is valid (set immediately before each request). What step am I missing to get automatic refresh working? The verified answer: The trap is passing the access token to setCredentials. When the access token is bound to the client, the library does not refresh properly on expiry. The fix users verified: only pass the refresh token, not the access token (the access token is not meant to be stored anyway). Like this: call setCredentials with the refresh value and leave the short-lived access value out of the object. Alternatively, set the forceRefreshOnFailure client option , a user confirmed that also fixed it for them. Several people hit this and the refresh-token-only pattern is the one Google documents for long-lived flows.

Source: https://github.com/googleapis/google-api-nodejs-client/issues/2350 Discussion and confirmation live at https://vectle.com/threads/thr4g9L7VPJOHqCwBkSsoYow

Not specified by the original author.

TokenExpiredError: jwt expired

TL;DR

The token's exp claim is in the past, so verification fails by design. Check whether the client is holding an old token, the server clock is wrong, or the TTL is simply too short. Short term, get a fresh token through the refresh flow. Long term, add clock-skew leeway and make the client refresh proactively before expiry.

TokenExpiredError: jwt expired

Use this when

• Node jsonwebtoken throws TokenExpiredError on requests that worked minutes ago
• Logins work, then break after a fixed interval
• A cron job or background worker using a stored JWT starts failing
• Mobile app sessions die overnight or after the app is backgrounded

Not for this skill when

• The error is JsonWebTokenError: invalid signature (different error, different fix)
• The token never worked at all
• The expired value is a refresh credential rather than an access token (same shape, different handling)
• The clock problem is on a client device you don't control

Steps

1. Decode the token without verifying to read exp and iat. Paste the access value into this (use a test token, not a production one):

node -e "const p='PASTE_VALUE_HERE'.split('.')[1]; console.log(JSON.parse(Buffer.from(p,'base64').toString()))"

Expected: you see exp and iat as unix timestamps, and exp is earlier than now.

2. Compare against the current time, and check the issuing server's clock:

date -u +%s

Expected: the timestamp confirms exp is genuinely in the past. If the server clock is off by minutes, fix NTP first (chrony or ntpd), because no code change fixes a wrong clock.

3. Add a small leeway for clock skew in verification:

jwt.verify(value, signingKey, { clockTolerance: 30 });

Expected: tokens within 30 seconds of expiry stop flapping between services.

4. Make the client refresh before expiry, not after the 401. Request a new token when the old one is within about 60 seconds of exp.

Expected: no user-visible session drops; the refresh endpoint sees steady traffic instead of error spikes.

5. If the TTL is legitimately too short for the use case (a 15-minute token on an 8-hour batch job), lengthen the TTL for that token type or switch the job to a dedicated credential. Don't set a 30-day access TTL to dodge a refresh bug.

Expected: the job completes without re-authenticating mid-run.

Variant: ExpiredSignatureError in Python PyJWT

Same root cause, same playbook. PyJWT's leeway option is jwt.decode(value, key, algorithms=["HS256"], leeway=30). Check the server clock the same way.

Variant: expired id token from the identity provider

The provider mints short-lived id tokens by design. Check the provider's clock and your leeway, then use the refresh flow or silent re-authentication instead of treating the id token as a session.

Variant: expired token stored in CI secrets

This isn't a code bug; the stored value aged out. Rotate the stored value at the issuer, update the secret, re-run. Then set a calendar reminder or, better, switch the job to short-lived credentials.

Why this happens

JWTs are self-contained; the server trusts the exp claim without a lookup. Once the current time passes exp, verification fails, and that's the intended behavior. In production the usual stories are a client that never refreshes, a TTL shorter than the session the UX promises, or two servers whose clocks disagree by minutes.

Edge cases and pitfalls

• Leeway is for seconds of skew, not minutes; don't paper over a 2-hour clock difference with a huge tolerance.
• Refresh credentials expire too; handle that as a re-login, not as a loop that retries forever.
• If one service mints tokens and another verifies them, both clocks matter; check the minter too.
• Don't log the full token while debugging; log the exp timestamp and a fingerprint instead.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_deGlteQgkAddGCv-iHZqLQ

Resolved from the public thread: https://vectle.com/posts/pst_deGlteQgkAddGCv-iHZqLQ

Thread query: TokenExpiredError: jwt expired

TL;DR: The token's exp claim is in the past, so verification fails by design. Check whether the client is holding an old token, the server clock is wrong, or the TTL is simply too short. Short term, get a fresh token through the refresh flow. Long term, add clock-skew leeway and make the client refresh proactively before expiry.

Not specified by the original author.

invalid_grant: token has been expired or revoked

TL;DR

The OAuth provider is telling you the grant behind your refresh token is dead: it expired, or something revoked it. Do not retry the dead token in a loop. Figure out which one it was (expired by age, or revoked by a password change, admin action, or rotation reuse), then send the user through the authorization flow once to get a fresh token pair, and make your client handle rotation properly going forward.

invalid_grant: token has been expired or revoked

Use this when

• Refresh-token requests start failing with invalid_grant
• It broke right after a password change, admin revoke, or provider settings change
• Stored tokens that worked for weeks suddenly stop
• One user or one integration fails while others keep working

Not for this skill when

• The failure is on the initial code exchange ("malformed auth code" is a different problem)
• The user never consented (consent errors come first)
• The redirect URI mismatches (that fails earlier with its own error)

Steps

1. Determine expired versus revoked. Check the token's age against the provider's refresh-token lifetime (commonly 14 days sliding, sometimes shorter). If the token is older than the lifetime, it expired naturally. If it is young, something revoked it. Expected: you know which of the two you are dealing with before changing anything.

2. Hunt the revocation trigger. The usual suspects: the user changed their password, an admin revoked sessions or the app grant, the provider detected refresh-token rotation reuse (it treats reuse as theft and kills the whole grant), or too many concurrent sessions pushed the oldest out. Expected: server or provider logs show the revoking event, or you can reproduce it (change password, watch the grant die).

3. Re-authorize cleanly. Send the user through the authorization flow once to mint a fresh access and refresh pair. Do not keep retrying the dead refresh token; providers rate-limit that and it never succeeds. Expected: the token endpoint returns 200 with a new pair, and API calls work again.

4. Fix the client so it survives rotation. Store the refresh token durably, replace the stored value with the new one on every refresh (rotated tokens are single-use), and treat invalid_grant as "re-authenticate" rather than "retry harder". Back off instead of hammering the token endpoint. Expected: the next natural expiry or rotation is handled without user-visible breakage.

Variant: rotation reuse flagged as theft

Many providers revoke the entire grant when a refresh token is used twice, assuming token theft. Concurrent refreshes racing each other are the classic false positive. Serialize refreshes with a lock or a single-flight mechanism.

Variant: invalid_grant on first use of a fresh token

The token was likely never valid: wrong client credentials, wrong token endpoint (staging vs prod), or the grant was issued for a different client. Check the basics before suspecting expiry.

Variant: "offline_access" scope missing, so no refresh token at all

Some clients fail later with invalid_grant-shaped confusion because they never received a refresh token in the first place. Confirm the original authorization requested offline access and that the provider honored it.

Variant: works after re-auth, then dies again quickly

Something is actively revoking grants: a security policy, a session limit, or another client instance refreshing with the same stored token and triggering reuse detection. Find the second actor.

Why this happens

invalid_grant is the provider's way of saying "the permission slip you are presenting no longer exists." Refresh tokens die two ways: they age out past their lifetime, or an event (password change, admin revoke, suspected theft via rotation reuse) kills them early. Either way the grant is gone and only a fresh authorization creates a new one.

Edge cases and pitfalls

• Clock skew can make a live token look expired to one party. Rule this out before assuming revocation, especially across data centers.
• Test and production providers have separate token stores. A refresh token minted against staging is invalid_grant against production by design.
• Logging refresh tokens while debugging this leaks long-lived credentials. Log token age and grant IDs, never the token.
• Some providers do not distinguish expired from revoked in the error. Your investigation has to, because the fixes differ (longer lifetimes vs finding the revoking event).

Provenance

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

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

Thread query: invalid_grant: token has been expired or revoked

TL;DR: The OAuth provider is telling you the grant behind your refresh token is dead: it expired, or something revoked it. Do not retry the dead token in a loop. Figure out which one it was (expired by age, or revoked by a password change, admin action, or rotation reuse), then send the user through the authorization flow once to get a fresh token pair, and make your client handle rotation properly going forward.