intercom oauth invalid authorization code error

Not specified by the original author.

Fix Intercom OAuth failing with invalid authorization code

TL;DR

Invalid authorization code means the code Intercom sent was already used, expired, or never valid. Authorization codes are single-use and expire in minutes, so exchange each code immediately and exactly once. If your code retries the exchange, the retry is what fails.

The error

Intercom OAuth failed
{"error":"invalid_grant","error_description":"Invalid authorization code"}

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=intercom oauth invalid authorization code error"

Fix it

Step 1: Check for double exchange in your code

Search your OAuth callback handler for the token exchange call and confirm it runs once per code.

Expected: You find either a single call or a retry path that reuses the code.

Step 2: Remove code reuse and retries

Make the exchange fire exactly once; on failure, restart the whole authorization flow instead of retrying the code.

Expected: Each authorization code is exchanged at most once.

Step 3: Exchange the code immediately

Keep the time between receiving the code and exchanging it as short as possible.

Expected: Exchanges complete within seconds of receiving the code.

Step 4: Verify the redirect URI matches

Confirm the redirect_uri sent at exchange time matches the one sent at authorize time.

Expected: Both values are identical.

Step 5: Test a fresh OAuth flow

Run the full flow again from authorization.

Expected: The exchange returns tokens on the first try.

When this applies

• Intercom OAuth fails with invalid authorization code
• The flow works sometimes and fails other times
• You added retry logic to the OAuth callback

When it doesn't

• The error is invalid_client (check the app credentials)
• The code is never received (check the redirect URI registration)
• Tokens are issued but API calls fail (check scopes)

Compatibility

Intercom OAuth 2.0 for apps. Authorization code flow.

Variant phrasings

intercom invalid_grant authorization code

Same failure. invalid_grant is the wrapper; the description names the code as the problem.

oauth code already used intercom

Already-used is the top cause when retry logic replays the exchange.

intercom oauth code expired

Codes expire quickly. Slow exchanges, like ones waiting on a user step, die before they run.

Why it happens

Authorization codes are single-use, short-lived credentials by design. The first exchange consumes the code; anything after that, a retry, a double-submit, a replayed webhook, gets invalid authorization code. Expired codes fail the same way when the exchange happens too late.

Edge cases

• Browser back-button resubmits can double-fire the exchange; guard with a state check
• Load-balanced callback handlers can race on the same code; make the exchange idempotent at the flow level
• Logging the code is a security risk; log the state parameter instead

If it still fails

• Reproduce with one API call in isolation, outside the agent, to separate platform issues from agent issues.
• Check the platform status page and changelog; OAuth and webhook behaviors change without warning.
• Capture the full request and response with timestamps for the vendor ticket, redacting credentials.
• Test in a second workspace or sandbox to rule out workspace-specific policy blocks.
• If the integration is business-critical, build the fallback now: cached data, a manual trigger, or a second provider.

Prevention

• Store OAuth credentials in a secrets manager with rotation reminders.
• Build the reconnect flow before you need it; every integration gets revoked eventually.
• Log token ages so expiring grants are visible ahead of time.
• Keep a sandbox integration for testing config changes.
• Document the required scopes per integration so reinstalls request the right ones.

Provenance

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

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

Thread query: intercom oauth invalid authorization code error

TL;DR: Invalid authorization code means the code Intercom sent was already used, expired, or never valid. Authorization codes are single-use and expire in minutes, so exchange each code immediately and exactly once. If your code retries the exchange, the retry is what fails.

Not specified by the original author.

Fix Intercom OAuth refresh failing with invalid_grant

TL;DR

The Intercom refresh token is dead - expired, revoked, or already consumed by a concurrent refresh - so the token endpoint returns invalid_grant. Get a fresh grant: send the workspace admin back through the Intercom OAuth flow, store the new token pair atomically, and make refresh failure trigger re-auth instead of an infinite retry loop. Also fix concurrent refreshes, which burn single-use refresh tokens.

The error

POST https://api.intercom.io/auth/eagle/token -> 400
{"error": "invalid_grant", "error_description": "The provided authorization grant is expired or revoked"}

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=intercom%20oauth%20token%20refresh%20failed%20invalid_grant"

Fix it

Step 1: Confirm invalid_grant is deterministic

Attempt one refresh and log the exact error body. One attempt is enough; repeated attempts cannot revive a dead grant.

Expected: invalid_grant again. Deterministic failure means the grant is dead, not the network.

Step 2: Stop the refresh loop and flag re-auth

Set the integration state to needs-reauth and stop all refresh attempts for that workspace.

Expected: no more doomed token calls. Every retry of a dead grant is wasted.

Step 3: Re-authorize through the Intercom OAuth flow

Direct the workspace admin to the Intercom app's OAuth authorize URL to grant access again.

Expected: a fresh authorization code. Only an admin of the Intercom workspace can re-grant.

Step 4: Exchange and store the new pair atomically

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

Expected: API calls succeed. Atomic storage prevents half-written pairs that fail the same way.

Step 5: Fix the refresh client

Add single-flight refresh (one in-flight refresh per workspace; concurrent callers wait for it) and make invalid_grant flip the integration to needs-reauth with an admin notification.

Expected: concurrent refreshes stop burning tokens, and the next death pages a human with a clear action.

When this applies

• Intercom refresh returns invalid_grant consistently
• The integration worked before and suddenly lost auth
• Failures follow a deploy that added concurrent workers

When it doesn't

• The authorize step itself fails (app config issue)
• The error is invalid_client (wrong client credentials)
• Refresh works but API calls 401 (access token handling bug)

Compatibility

Intercom OAuth 2.0, app store integrations, token endpoint auth/eagle/token.

Variant phrasings

intercom refresh token expired invalid_grant

Expiry and revocation look identical here. The recovery is the same: fresh grant.

intercom oauth reauthorize invalid grant

Re-authorization is the only recovery path. There is no refresh of a dead grant.

Why it happens

Intercom refresh tokens have a limited lifetime and behave as single-use in practice: once a refresh succeeds, the old token is consumed. Two workers refreshing concurrently will have one winner and one invalidgrant loser, and the loser's "retry" then kills the winner's new token too. Add expiry or revocation on top, and invalidgrant is the terminal state. Only a fresh interactive grant mints a new pair.

Edge cases

• Concurrent refresh is the most common self-inflicted cause; single-flight it before anything else
• Clock skew is rarely the cause here; do not chase NTP
• Rotating refresh on every use means the store write must be atomic or races corrupt it

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_iEudIIbuJS8p7rKmkE631A

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

Thread query: intercom oauth token refresh failed invalid_grant

TL;DR: The Intercom refresh token is dead - expired, revoked, or already consumed by a concurrent refresh - so the token endpoint returns invalid_grant. Get a fresh grant: send the workspace admin back through the Intercom OAuth flow, store the new token pair atomically, and make refresh failure trigger re-auth instead of an infinite retry loop. Also fix concurrent refreshes, which burn single-use refresh tokens.

Not specified by the original author.

Fix Notion OAuth failing with restrictedtoworkspace

TL;DR

The Notion integration is restricted to a specific workspace - either it is an internal integration, which by design installs only in its home workspace, or the target workspace blocks outside integrations. Install it in the allowed workspace, or convert it to a public integration and complete Notion's review for cross-workspace distribution. The workspace admin decides which path applies.

The error

OAuth callback error: "restricted_to_workspace"
The integration cannot be installed in this workspace

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=notion%20oauth%20restricted_to_workspace%20install%20error"

Fix it

Step 1: Check the integration type

Open notion.so/my-integrations, select the integration, and check whether it is internal or public.

Expected: the type is confirmed. Internal integrations can only ever install in their home workspace; that restriction is not a bug.

Step 2: Install in the correct workspace if internal is fine

Have a workspace owner of the home workspace add the integration under Settings / Connections.

Expected: the install succeeds there. If the product only ever serves one workspace, stop here.

Step 3: Convert to public for multi-workspace distribution

In the integration settings, change the distribution to public and submit it for Notion's review.

Expected: after approval, the integration installs in any workspace. Plan for review time; it is not instant.

Step 4: Check the target workspace's integration policy

In the target workspace's Settings, confirm whether workspace owners allow public integrations or require approval for each one.

Expected: the policy allows the install, or the approval request is submitted. A workspace-level block overrides everything else.

Step 5: Retry the OAuth flow from the right workspace

Start the OAuth flow while acting in the correct workspace context and complete the authorization.

Expected: authorization completes and the token works.

When this applies

• OAuth fails with restrictedtoworkspace
• The integration installs in one workspace but not another
• Distributing a Notion integration to customer workspaces

When it doesn't

• The error is invalid authorization code (code reuse or expiry)
• The redirect URI mismatches (app config issue)
• API calls fail after a successful install (capability or permission issue)

Compatibility

Notion API OAuth 2.0, internal vs public integrations.

Variant phrasings

notion integration restricted to workspace

Check the integration type first; the fix depends entirely on internal vs public.

notion oauth error restrictedtoworkspace

The error names the restriction. Match the distribution model to where it must install.

Why it happens

Notion scopes internal integrations to a single workspace by design: they are meant for first-party, single-workspace use. Cross-workspace installation requires the public distribution model plus Notion's review. The error fires whenever the install target falls outside the integration's allowed distribution, which is working as intended.

Edge cases

• Only workspace owners can install integrations; members hit a permissions wall that looks similar
• Review turnaround for public integrations varies; do not promise customers a date
• Duplicating an internal integration per workspace is a common workaround for a handful of workspaces

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/pstdg56RzQRnKJCFAnJCiwGQ

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

Thread query: notion oauth restrictedtoworkspace install error

TL;DR: The Notion integration is restricted to a specific workspace - either it is an internal integration, which by design installs only in its home workspace, or the target workspace blocks outside integrations. Install it in the allowed workspace, or convert it to a public integration and complete Notion's review for cross-workspace distribution. The workspace admin decides which path applies.