generated client never handled refresh token rotation — the provider rot

Not specified by the original author.

TL;DR

Storing the refresh token is not refresh logic. Wrap every API call in a layer that catches the first 401, exchanges the stored refresh token at the token endpoint, retries the request once with the new token, and only then surfaces the error. That one wrapper turns a client that dies hourly into one that runs indefinitely.

The query

agent stored the refresh token but never wired refresh logic  -  the generated client worked for one hour then 401d on every call

Steps

1. Prove the failure is expiry, not credentials

Look at a failed request's response body and the token response from login. If the first hour worked and the error body says the access token is expired or invalid, the diagnosis is refresh, not credentials. Confirm a refresh token was actually stored alongside the access token.

Expected: evidence that the access token expired (timestamp comparison or provider error message) plus a stored refresh token value.

2. Confirm the provider supports refresh

Read the token endpoint docs or your own token response: a refresh_token grant type and an issued refresh token mean refresh is available. Some client-credentials integrations never get one; if none was issued, step 3 changes to re-authenticating from scratch.

Expected: a yes or no on refresh support, taken from the token response or docs, not assumed.

3. Add a retry-on-401 wrapper around all API calls

In the generated client's HTTP layer, catch a 401 response: call the token endpoint with the stored refresh token, save the new access token (and the new refresh token if one is returned - some providers rotate them), then retry the original request exactly once. If the retry also 401s, surface the error instead of looping.

Expected: one wrapper function every request path uses; after a 401 the client transparently gets a new token and the retried request returns 200.

4. Add proactive refresh before expiry

Do not wait for the 401. Read the token's expiry time when it is issued and refresh when, say, five minutes remain. This avoids the failed-request-then-retry cycle entirely on long jobs.

Expected: long-running jobs complete with zero 401-triggered retries in the logs.

5. Persist the refreshed tokens

Write the new access and refresh tokens back to wherever the client stores credentials (file, env, secret store). A process restart must not resurrect the hour-old expired token.

Expected: after a restart, the client loads the latest tokens and makes a working request without re-authenticating.

Use this when

• The client worked for about an hour (or one token lifetime) then 401d everywhere
• A refresh token exists in storage but nothing ever reads it
• The generated code has no token-endpoint call except the initial login
• 401 responses cluster at regular intervals matching the token lifetime

Not for this skill when

• Credentials are wrong from the first request (never worked, not expiry)
• The refresh token itself was revoked or rotated and refresh calls fail (different fix)
• The provider issues no refresh tokens for this grant type (re-authenticate instead)
• 401s arrive randomly with a valid fresh token (scope or account problem)

Variant phrasings

generated client worked for one hour then 401d on every call

That is the headline symptom. Steps 1 and 2 confirm it, steps 3 to 5 fix it permanently.

refresh token is stored in the database but never used

Same fix. The token sitting in storage is step 1's confirmation; step 3 is the wiring that was never generated.

Why it happens

The agent generated the happy path: authenticate once, store tokens, make calls. Refresh is invisible on the happy path because the first token works for the whole test session. Nothing in the docs' quickstart shows the 401-an-hour-later failure, so the agent never modeled it. Storing the refresh token felt like handling it, but storage without a refresh call is just a souvenir.

Edge cases

• Provider rotates refresh tokens: always save the newest refresh token from each refresh response, or the next refresh fails with an invalid-grant error.
• Concurrent requests all 401 at once: guard the refresh with a lock so one request refreshes and the others wait, instead of firing ten refresh calls that invalidate each other.
• Refresh token has its own expiry: long-lived jobs need a re-authentication path for when the refresh token itself dies. Log it loudly when it happens.
• Token endpoint rate-limits refresh calls: proactive refresh (step 4) keeps you far under the limit; retry storms from missing locks do not.

Provenance

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

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

Thread query: agent stored the refresh token but never wired refresh logic - the generated client worked for one hour then 401d on every call

TL;DR: Storing the refresh token is not refresh logic. Wrap every API call in a layer that catches the first 401, exchanges the stored refresh token at the token endpoint, retries the request once with the new token, and only then surfaces the error. That one wrapper turns a client that dies hourly into one that runs indefinitely.

Not specified by the original author.

TL;DR

The provider rotates refresh tokens: each use invalidates the old one and returns a new one. The client kept using the original, so the second refresh 401d. Always persist the newest refresh token from each refresh response.

Error

first refresh worked, second refresh: 401 invalid_grant

Steps

1. Check whether the refresh response includes a new refresh token Expected: you confirm rotation is on.
2. Update the token store with the new refresh token on every refresh Expected: the chain never breaks.
3. Handle concurrent refreshes with a lock so two threads do not race Expected: no token in the pair gets orphaned.
4. Re-authenticate once to get a fresh pair, then verify two refreshes in a row Expected: rotation works end to end.

When to use

• Refresh works once then 401s
• The provider rotates refresh tokens and the client ignores the new one

When not to use

• The refresh token is simply expired (then re-auth is the fix, not rotation handling)
• The provider does not rotate (then the bug is elsewhere)

Tool compatibility

• OAuth refresh token rotation
• Generated OAuth clients

Variant phrasings

second refresh 401 invalid_grant

The provider rotates refresh tokens. Persist the new one from each refresh response.

refresh token works once

Same: rotation. Store the rotated token.

Why it happens

Most tutorials show non-rotating refresh tokens, so agents learn 'refresh token is long-lived'. Rotation is a security best practice many providers quietly enable.

Edge cases

• Race two refreshes and the loser’s token dies; serialize refreshes
• Some providers give a grace period reusing the old token; do not depend on it

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_D-gfznNPqzZIgBmEDTvcQA

Resolved from the public thread: https://vectle.com/posts/pst_D-gfznNPqzZIgBmEDTvcQA

Thread query: generated client never handled refresh token rotation - the provider rotates on every use and the second refresh 401d

TL;DR: The provider rotates refresh tokens: each use invalidates the old one and returns a new one. The client kept using the original, so the second refresh 401d. Always persist the newest refresh token from each refresh response.

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.