Skip to main content

Integration OAuth Troubleshooting

Use this guide when an integration that relies on vendor OAuth stops authenticating, returns authorization errors, or fails after you change something in your identity or security admin console. It summarizes how OAuth fits Catalog integrations, groups problems by symptom, and points you to integration-specific setup where behavior differs by product.

If you use Transform in the Coalesce App, Snowflake OAuth for Workspace connections is documented in Snowflake OAuth. Catalog Public API authentication uses API tokens as described in Catalog Public API.

How Catalog Uses OAuth for Integrations​

Catalog reaches external systems through integrations you configure under Settings > Integrations in Coalesce Catalog. Some integrations authenticate with vendor OAuth, including consent screens, client id and secret, authorization codes, or refresh tokens. Others use API keys, personal access tokens, or username and password. The integration’s own documentation is the source of truth for which model applies.

When OAuth is in play, Catalog needs credentials that match the OAuth app or equivalent registration in your vendor admin console. Typical failure causes are expired or revoked tokens, a redirect URI or callback URL that no longer matches what the vendor expects, missing or insufficient API scopes, or a client id or secret that changed and was not updated in Catalog.

Decide Whether OAuth Is the Right Layer To Fix​

Use this quick check before you change network rules or re-run a full extraction:

  • The integration’s guide names OAuth, Google sign-in, or client id and secret - Treat the problem as OAuth-related and follow the symptom sections below, then the vendor section in that guide.
  • The guide centers on an API key or personal access token - Confirm the key is current, assigned to the right service identity, and pasted correctly in Settings > Integrations. OAuth flows in this hub usually do not apply.
  • Looker compared with Looker Studio - Classic Looker uses API keys in Catalog. Looker Studio uses Google OAuth. Do not mix steps between those guides or you can see authentication errors. See Looker and Looker Studio.

Sync Fails, Stalls, or Looks Stale After a Vendor Change​

This pattern often follows a password rotation, client secret rotation, OAuth policy change, or account lockout in the vendor system.

  1. In the vendor admin console, confirm the OAuth app or integration user is still active, approved, and allowed to use the flows Catalog needs, for example, client credentials or refresh tokens, depending on the product.
  2. If you rotated secrets or regenerated keys, copy the new values from the vendor console.
  3. In Coalesce Catalog, open the Integration settings page in the app, select the source, and use Edit credentials, or the equivalent control your integration shows, to save updated JSON or fields your onboarding documented.
  4. Trigger or wait for the next sync using your normal Catalog-managed or client-managed process. If failures continue, capture the error text or time stamp your vendor or Catalog contact can use.

Redirect URI, Callback URL, or Environment Mismatch​

Vendors often validate the exact callback or redirect URI registered for the OAuth client. A mismatch produces errors that mention redirect URIs, callbacks, or invalid redirect.

  1. Open the OAuth app settings for that integration in the vendor console and read the allowed redirect or callback URLs.
  2. Compare them to the values required for Catalog or listed in the integration guide. Some products use a fixed Catalog callback; others accept a placeholder when the flow does not use a browser redirect.
  3. Update the vendor registration to match the documented pattern, or create a new OAuth client if your vendor does not allow edits.
  4. Update saved credentials in Catalog if the client id, secret, or related fields changed when you fixed the registration.

Insufficient Scope or Access Denied Immediately After Setup​

If authorization completes in the vendor UI but API calls fail right away, scopes or API access for the OAuth client are a common cause.

  1. Reopen the integration guide for your product and confirm every required OAuth scope or permission is enabled on the vendor side.
  2. For products that require admin consent or security review, complete that step in the vendor tenant.
  3. Save credentials again in Catalog after scope changes so the next run uses the updated consent.

Authorization Codes Expire Before You Paste Them​

Some flows issue short-lived authorization codes that often expire within minutes. If the code expires before Catalog receives the full credential bundle, authentication fails even when the client id and secret are correct.

  1. Generate a new authorization code in the vendor console immediately before you send or paste it.
  2. For Zoho Self Client and similar flows, work through the handoff in the same session when possible. See Zoho for regional hosts, required scope, and timing.

Update Credentials in Catalog After Fixing the Vendor Side​

After you correct the OAuth app or tokens in the vendor system, Catalog still needs the latest values.

  1. Sign in to Coalesce Catalog and open Settings > Integrations. You can also bookmark the Integration settings page in the app.
  2. Open the integration that is failing.
  3. Choose Edit credentials, or your source’s credential editor, and enter the updated client id, client secret, tokens, or JSON bundle exactly as your integration guide specifies.
  4. Save and monitor the next extraction or sync outcome.

Exact field names and JSON shapes differ by integration. Always align with the guide for that integration.

Integration-Specific Guides​

These pages carry the detailed OAuth setup and product-specific edge cases:

  • Salesforce - External Client App, OAuth scopes, client credentials flow, IP relaxation, refresh policy, and connection tests.
  • Zoho - Self Client codes, regional server_uri, required scope, and common OAuth handoff failures.
  • Looker Studio - Google OAuth for Catalog-managed setup, which differs from classic Looker API keys.

Add or follow links from other integration pages as your stack grows; this hub stays focused on shared OAuth patterns.

When To Contact Your Catalog Contact​

Reach out when you have completed the checks for your symptom, updated credentials in Catalog, and failures persist, or when your organization needs help interpreting vendor error messages against Catalog’s ingestion model. Include the integration name, approximate time of failure, and any vendor error text you can share. Redact secrets before you send them.

What's Next?​