Symptom: Tools for a specific integration start returning errors after working fine for days or weeks. The error message mentions "token refresh" or "unauthorized."

Cause: The refresh token has been invalidated. This can happen if you revoked Ferrule's access from the third-party service's settings, if the provider expired a long-lived refresh token, or if you re-authorized the integration in a way that invalidated the previous token.

Solution:

1. Open Dashboard → Integrations and click Disconnect next to the affected integration.
2. Click Connect and complete the OAuth flow again.
3. Generate a new API key or use your existing one — Ferrule will automatically use the newly stored tokens.

Symptom: When you try to reconnect an integration, the OAuth flow fails with an "invalid_grant" error, or Ferrule shows a connection error after the redirect.

Cause: The authorization code returned by the provider has already been used or has expired (most providers expire codes in 60 seconds).

Solution:

1. Start the connection flow again from Dashboard → Integrations → Connect. Do not use the browser back button or reload the callback URL.
2. Complete the provider's authorization screen promptly — do not leave it open for more than a minute before approving.
3. If the error persists, clear your browser cookies for the provider's domain and try again from a fresh tab.

Symptom: The integration connects successfully but specific tools return "insufficient scope" or "permission denied" errors from the upstream API.

Cause: The OAuth scopes Ferrule requested do not include the permissions needed for the tool you are calling. This can happen if you approved a reduced set of permissions during the OAuth flow, or if the provider requires additional scopes for certain API endpoints.

Solution:

1. Disconnect and reconnect the integration from the Ferrule dashboard. When the provider shows the permissions screen, accept all requested scopes.
2. If the provider asks you to choose between minimal and full access, choose full access (or the scope set that Ferrule requests).
3. If you manage the OAuth application yourself, verify the application's configured scopes match what Ferrule's integration requires.

Symptom: The OAuth flow fails immediately after you approve access, with an error from the provider saying "redirect_uri_mismatch" or similar.

Cause: The redirect URI registered in the OAuth application on the provider's developer console does not match the URI Ferrule sends during the flow.

Solution:

This error typically means the provider's OAuth application has a misconfigured redirect URI. Contact Ferrule support with the provider name and the exact error message — the team will verify the redirect configuration and resolve the issue.

Symptom: Box tools work once after connecting but fail on subsequent calls with a token error.

Cause: Box uses single-use refresh tokens: each time a refresh token is used to obtain a new access token, a new refresh token is issued and the old one is invalidated. If a concurrent request uses the old refresh token before Ferrule stores the new one, the token chain breaks.

Solution:

1. Disconnect and reconnect Box from Dashboard → Integrations.
2. Avoid running concurrent requests against the Box integration immediately after connecting — let the first request complete and let Ferrule store the refreshed tokens before sending more.
3. If the issue recurs under load, contact Ferrule support. The gateway serializes token refreshes per integration, but very high concurrency can still expose this race.

Symptom: Google Drive, Google Docs, Google Analytics, or Google Search Console integrations work initially but fail after the access token expires (typically 1 hour). Reconnecting temporarily fixes the issue.

Cause: Google only issues a refresh token when prompt=consent is included in the authorization request. If you previously authorized Ferrule without seeing the consent screen (because you had granted access before), Google may not issue a new refresh token.

Solution:

1. Open the Google Account Permissions page and revoke Ferrule's access for the affected Google service.
2. Return to Dashboard → Integrations and reconnect the integration.
3. Google should now show the full consent screen and issue a refresh token.