{"slug":"business/connector-oauth-troubleshooting","title":"Connector OAuth Troubleshooting Runbook","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/connector-oauth-troubleshooting.mdx","bytes":2091,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nUse this runbook when connector authorization, callback handling, or tenant-scoped OAuth flows fail.\n\n## Common Symptoms\n\n- user is redirected back with an error\n- callback route returns 4xx or 5xx\n- connector shows disconnected immediately after auth\n- state or tenant context is missing\n- provider says redirect URI mismatch\n\n## First Checks\n\n1. Identify the provider and tenant.\n2. Confirm which live path is responsible for the flow.\n3. Check whether the issue is:\n   - one tenant\n   - one provider\n   - all OAuth flows\n\n## Verify Provider Configuration\n\n- client ID and secret are present in the correct environment\n- redirect URI exactly matches the live callback path\n- requested scopes match current product behavior\n- provider app is not disabled, rate limited, or restricted\n\n## Verify IntegrateWise Configuration\n\n- Gateway and connector routes are deployed and healthy\n- callback route matches current code and environment\n- tenant and user context are preserved through the state parameter or session flow\n- any required secret rotation did not leave stale values in Cloudflare\n\n## Logs And Evidence To Check\n\n- callback request status and body\n- state or tenant resolution failures\n- provider error codes returned on callback\n- connector write or credential persistence failures after callback\n- correlation ID for the full auth round trip, if available\n\n## Safe Recovery Steps\n\n1. Fix redirect URI, secret, or scope mismatch.\n2. Re-test in a single tenant before wider rollout.\n3. Confirm connector status stays connected after callback.\n4. Trigger a minimal sync or status check to validate the connection.\n\n## Do Not\n\n- broaden scopes casually without product review\n- rotate provider secrets mid-incident without recording the change\n- test across many tenants before one known-good tenant passes\n\n## Related Docs\n\n- [../WEBHOOKS_AND_SLACK_APP.md](../WEBHOOKS_AND_SLACK_APP.md)\n- [../architecture/PRODUCT_ARCHITECTURE_FROM_CODE.md](../architecture/PRODUCT_ARCHITECTURE_FROM_CODE.md)\n- [incident-response.md](incident-response.md)\n"}