OAuth Integration Stopped: Refresh the Token or Reconnect?
Start with the short answer ↓
When a business integration loses access, distinguish a refreshable access token from a rejected grant or missing permission. Pause affected work visibly, use an authorized recovery path and reconcile pending actions before resuming.
Prepared with AI assistance. These are practical scoping recommendations; examples are illustrative, not client results.
Start with the unfinished task, not a generic reconnect button
A CRM-to-operations connection worked yesterday, but new service jobs are now waiting. The team sees an authorization error and keeps pressing retry. Before changing credentials, identify which account and operation failed, the last successfully verified work and the requests that remain unfinished. This is an illustrative planning scenario, not a customer incident or a claim about a delivered connector.
Access recovery and business recovery are different decisions. Obtaining a usable token does not prove that a job was created, that an earlier attempt failed or that the queue belongs to the account just connected. Keep these questions visible while the technical owner diagnoses the actual provider response.
Confirm the account and operations the integration actually needs
Separate a failed access token from a failed grant
OAuth separates permission granted to an application from an access token used for a resource request. Where a provider issues a usable refresh token, its supported refresh flow can obtain another access token without asking the user to sign in for every expiry. Google's web-server guidance documents this distinction and notes that losing the refresh token can require the consent flow again. Do not assume that every integration receives one or shares the same token lifetime.
RFC 6750 distinguishes invalid_token from insufficient_scope: the former ordinarily uses HTTP 401, while the latter ordinarily uses HTTP 403 for a request beyond the token's privileges. Those are bearer-token protocol meanings, not proof that every 401 is simple expiry or every provider's 403 means the same thing. Inspect the endpoint, documented error category and relevant response details before choosing a recovery action.
Use a small access-loss decision worksheet
The worksheet below is our proposed operating contract, not a universal error handler. In particular, RFC 6749 gives invalid_grant several possible causes, including an invalid, expired or revoked refresh token and mismatched client or redirect information. A label alone does not prove that the user revoked access. Record the observed cause separately from an unverified explanation.
| Observed condition | Permitted recovery path | What must stay visible |
|---|---|---|
| The documented access-token refresh path remains usable | Refresh through the supported client, within existing permissions; do not loop indefinitely if it fails. | Which operation was blocked and whether any business outcome remains uncertain. |
| The refresh request returns invalid_grant | Stop repeating the unchanged rejected request. Verify configuration and provider guidance; an authorized person may need to reconnect. | The affected account, recovery owner and work paused pending the decision—not the credential value. |
| The operation lacks the required scope or account role | Review the actual business need and existing grant. Additional access requires its own approval; a fresh token is not permission expansion. | The denied operation and a permitted alternative or escalation. |
| The failure is not yet classified | Use the provider's documented diagnostic path before changing access or resuming consequential work. | What is known, what remains unknown and who will check it next. |
Keep throttling and request-budget recovery separate from access recovery
Reconnect the intended business account without expanding authority
Name the person who may authorize reconnection and how they confirm the provider, business account, environment and application. A browser may already be signed in to a personal or different customer account. A successful consent screen is not enough: verify the returned account context through the provider's supported method before attaching it to waiting work.
Request only the agreed operations. The OAuth refresh rules do not allow a refresh request to expand the original scope. If the workflow genuinely needs more access, treat that as a separate approved change rather than silently reconnecting with administrative permissions. Respect an intentional revocation; do not work around it with another employee's unmanaged account.
Keep access tokens, refresh tokens and client secrets out of project briefs, URLs, screenshots and diagnostic messages. Use the existing authorized secret-handling mechanism and provider-supported libraries. This guide is a scoping aid; it does not ask anyone to rotate credentials, alter account policies or weaken protections on a live system.
Assign continued access and provider notices to an operating owner
Resume the work, not just the connection indicator
Consider two invented requests, J19 and J20, waiting during an access interruption. J19 has not been sent. Staff completed J20 manually in the destination while the connection was paused. Restored access should not cause the integration to create both jobs again. The proposed recovery view separates eligible unsent work, work with an uncertain outcome and work already matched to a destination record.
After verifying the account, demonstrate a permitted operation using an approved test environment or existing controlled test arrangement. Then reconcile the saved business references and checkpoint before releasing the backlog. J19 may proceed through its normal checks; J20 needs its existing result linked and verified. If an earlier write's result cannot be established, keep that case under review instead of inventing absence.
Restart with an agreed processing limit and verify useful business completion. A new token's issue time is not the data-through time for the queue. Display the last completed checkpoint, oldest waiting task, reason for any pause and named owner. Keep unaffected workflows running only where their access and business dependencies are genuinely independent.
Resolve uncertain business outcomes before repeating a write
Accept expiry, denial and reconnection as different test cases
Use isolated credentials or a simulated provider, with production sending and consequential writes disabled. Demonstrate ordinary access-token expiry with a supported refresh, a rejected refresh grant, a denied operation, reconnection to the wrong account, cancellation of reconnection and staff completion of a pending job during the pause. Follow the provider's test options rather than revoking a real customer's access to create the exercise.
For each case, agree what may run automatically, when processing stops and who can authorize the next step. Acceptance needs evidence of the correct account, permitted operation, preserved work identity and understandable exceptions. Confirm that the operator sees a real next action without exposing a secret. A green connection badge alone does not demonstrate restored business service, and no fixed reconnection time should be promised without the required owner and provider access.
Primary references
The guidance above is AgenticShip's proposed approach. These references provide technical background for the relevant recommendations.