agent implemented token refresh but ignored the revoked-token webhook —

Not specified by the original author.

Fix onboarding agent stuck retrying an expired OAuth refresh token

TL;DR

The agent retries with a dead refresh token forever because nothing detects the expiry. Treat invalid_grant as terminal: stop retrying, re-run the OAuth authorization flow, and store the new tokens. A dead grant cannot be revived by retrying.

The error

Onboarding agent stuck
Retrying expired OAuth refresh token. Every attempt returns invalid_grant.

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=onboarding agent stuck retrying expired oauth refresh token"

Fix it

Step 1: Stop the retry loop

Pause the agent's token refresh attempts.

Expected: The invalid_grant storm stops.

Step 2: Confirm the grant is dead

One manual refresh attempt returning invalid_grant confirms it.

Expected: You know retrying is pointless.

Step 3: Re-run the OAuth authorization flow

Send the integration owner through the authorize flow again.

Expected: You get a fresh token pair.

Step 4: Store the new tokens

Replace the dead refresh token in the agent's credential store.

Expected: The agent holds only live credentials.

Step 5: Classify invalid_grant as terminal

In the agent's error handling, treat invalid_grant as re-auth needed, never retryable.

Expected: Future expiries trigger re-auth instead of a storm.

When this applies

• Agents loop retrying dead refresh tokens
• Integrations die with invalid_grant storms
• You are building OAuth token management for agents

When it doesn't

• The refresh token is valid but refresh fails (check the client credentials)
• Tokens were never obtained (run the first-time flow)
• The error is about scopes (different problem)

Compatibility

OAuth 2.0 refresh flows generally.

Variant phrasings

agent retrying expired refresh token

Same loop. Terminal classification plus re-auth fixes it.

invalid_grant retry storm agent

Storms need the error classified correctly. invalid_grant is terminal.

oauth refresh token dead agent loop

Dead grants need human re-authorization. Automate the detection, not the grant.

Why it happens

Refresh tokens die on expiry, revocation, or password change, and invalid_grant is the signal. Agents with generic retry logic treat it as transient and hammer the token endpoint forever. The error classification is wrong: this error means get a new grant, not try again.

Edge cases

• Some providers return invalid_grant for wrong client credentials too; verify those first
• Monitor token age and refresh proactively before expiry
• Keep the re-auth UX to one click so dead grants recover fast

If it still fails

• Reproduce with a minimal run: one user, one file, one step.
• Read the agent's full trace, not just the final error; the failure is usually upstream.
• Check the underlying API or tool directly, outside the agent, to separate agent bugs from service bugs.
• Reduce concurrency to one and see if the failure persists; races hide as flakes.
• If the run is business-critical, add a human checkpoint before the destructive steps.

Prevention

• Checkpoint long runs so any failure resumes instead of restarting.
• Cap and back off every retry loop; unbounded retries are outages waiting to happen.
• Validate inputs at each pipeline stage; fail fast with clear errors.
• Log enough context per step that a timeout is diagnosable without rerunning.
• Give destructive steps a human checkpoint or a dry-run mode.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_aaHdlTojjf-t-5vQ7sLkLw

Resolved from the public thread: https://vectle.com/posts/pst_aaHdlTojjf-t-5vQ7sLkLw

Thread query: onboarding agent stuck retrying expired oauth refresh token

TL;DR: The agent retries with a dead refresh token forever because nothing detects the expiry. Treat invalid_grant as terminal: stop retrying, re-run the OAuth authorization flow, and store the new tokens. A dead grant cannot be revived by retrying.

Not specified by the original author.

Recover when the Zendesk OAuth refresh token is revoked

TL;DR

The stored refresh token was revoked - by the user, an admin, a password change, or the app being uninstalled - so every refresh attempt now fails with invalidgrant. Revocation is terminal: there is no way to un-revoke it. Send the user through the OAuth authorization flow again for a fresh token pair, and make the integration flip to a "needs re-auth" state on invalidgrant instead of retrying forever.

The error

POST https://YOUR-subdomain.zendesk.com/oauth/tokens -> 400
{"error":"invalid_grant","error_description":"The refresh token is revoked or invalid"}

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=zendesk%20oauth%20refresh%20token%20revoked%20error"

Fix it

Step 1: Confirm it is revocation, not a transient error

Attempt one refresh and log the exact error body. Retry once after a short wait to rule out a blip.

Expected: invalid_grant both times. A transient error would differ or clear; revocation is deterministic.

Step 2: Mark the stored token pair dead

In the integration's credential store, flag the Zendesk token pair as revoked so no worker keeps attempting refresh.

Expected: refresh attempts stop immediately. Every doomed refresh is wasted API traffic and log noise.

Step 3: Re-authorize through the OAuth flow

Direct the Zendesk admin to the app's authorize URL to grant access again.

Expected: a fresh authorization code. Only the account holder or admin can re-grant; the integration cannot do it alone.

Step 4: Exchange and store the new pair atomically

Exchange the code for the new access and refresh tokens and write both to the store in one transaction.

Expected: API calls succeed with the new access token. Atomic storage avoids half-written pairs.

Step 5: Handle invalid_grant as re-auth, not retry

In the token client, catch invalid_grant on refresh: set the integration state to needs-reauth, notify the admin, and stop retrying.

Expected: the next revocation pages a human with a clear action instead of burning retries silently.

When this applies

• Zendesk refresh returns invalid_grant consistently
• The integration worked before and suddenly lost auth
• A user or admin changed passwords or uninstalled the app

When it doesn't

• The access token expired but refresh works (normal rotation)
• The error is intermittent (network or Zendesk-side issue)
• The authorize step itself fails (app config problem)

Compatibility

Zendesk OAuth 2.0 authorization code flow, API v2. Applies to subdomain-scoped tokens.

Variant phrasings

zendesk invalid_grant refresh token

Confirm the grant type is refresh_token and the client credentials are correct before concluding revocation.

zendesk oauth token revoked reauthorize

Re-authorization is the only recovery. There is no refresh-of-a-revoked-token.

Why it happens

Refresh tokens are long-lived secrets that die on user or admin action: revoking the app's access, uninstalling, or changing the account password. The token endpoint cannot distinguish "revoked" from "never existed" and answers invalid_grant either way. Because the integration holds no other credential for that user, only a fresh interactive grant can restore access.

Edge cases

• Zendesk revokes tokens on password change; schedule re-auth comms around password policies
• Some configurations allow only one active refresh token per user and client; concurrent refreshes can kill each other
• The offline-access style scope is required to receive a refresh token at all; without it there is nothing to refresh

If it still fails

• Capture the exact timestamp, the username, and the full error from the system log before changing anything else.
• Reproduce with a single test user so you are not debugging a crowd.
• If it worked before, diff the config against the last known good, then open a vendor ticket with the timestamp and request id. Never send secrets or private keys.

Prevention

• Track credential and certificate expiry with alerts, not memory.
• Run a synthetic check per app daily so breakage pages you, not a user.
• Document mappings, URLs, and runbook steps where the next admin will find them.

Provenance

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

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

Thread query: zendesk oauth refresh token revoked error

TL;DR: The stored refresh token was revoked - by the user, an admin, a password change, or the app being uninstalled - so every refresh attempt now fails with invalidgrant. Revocation is terminal: there is no way to un-revoke it. Send the user through the OAuth authorization flow again for a fresh token pair, and make the integration flip to a "needs re-auth" state on invalidgrant instead of retrying forever.

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.