agent confused the provider's two token endpoints — it sent the refr

Not specified by the original author.

TL;DR

Do not trust the docs' prose about OAuth flows. Before generating auth code, check the provider's token endpoint behavior or its OpenID discovery document for the grant types it actually supports, then generate for the flow that fits a machine client. A 2-minute smoke test of a token request catches what doc-reading misses.

The query

scaffolder agent generated OAuth code against the wrong flow - the docs described auth-code flow but the API only supports client-credentials

Use this when

• Generated code implements an authorization-code redirect that can never complete
• The provider is a machine-to-machine API with no user login step
• The docs mention OAuth2 but never show a working token request for your client type
• The generated client 400s on the token endpoint with an unsupported-grant-type error

Not for

• Tokens that expire and never refresh (refresh wiring, different problem)
• Wrong client ID or secret (credential problem, not flow problem)
• Scope errors on a token request that otherwise works
• APIs that use API keys instead of OAuth entirely

Steps

1. Find the ground truth, not the prose

Fetch the provider's OpenID discovery document if it has one: https://YOUR-provider-domain/.well-known/openid-configuration, and read the grant_types_supported field. No discovery doc? Read the token endpoint's error responses instead of the marketing docs.

Expected output: the actual list of supported grant types, e.g. ["client_credentials", "refresh_token"].

2. Match the flow to the client type

A scaffolder generating a server-side integration with no browser and no user is a machine client. That means client_credentials, not auth-code, not PKCE, not implicit. If the docs' example shows a browser redirect, the example is for a different client type than the one being built.

Expected output: one chosen flow, justified by the client type, not by which example the docs put first.

3. Regenerate the auth module for the right flow

Generate the token request for client-credentials: POST to the token endpoint with grant_type=client_credentials, client ID and secret in basic auth or the body per the provider's docs, and the required scope.

Expected output: a token-request function with no redirect URL, no authorization endpoint, no code exchange.

4. Smoke-test a token request before wiring anything else

Run one real token request with the generated code and confirm a 200 with an access token. Do not generate the other 40 endpoints first.

curl -s -X POST "https://YOUR-provider-domain/oauth/token" -u "[client id]:[client secret]" -d "grant_type=client_credentials&scope=[scope]" | head -c 300

Expected output: a JSON response containing an access token, not an unsupported_grant_type error.

5. Record the flow decision in the generated code

Leave a comment at the top of the auth module: which flow, why (machine client, no user), and where the ground truth came from (discovery URL or token-endpoint behavior). The next agent that regenerates this client reads the comment, not the docs.

Expected output: the flow decision is documented in the code, not just in someone's head.

Variant phrasings

agent implemented OAuth PKCE for a machine-to-machine integration

Same fix. PKCE is for public clients with a user present; a server-side agent has neither. Step 2 settles it.

docs said OAuth2 without specifying the flow

Treat unspecified as unknown, not as auth-code. Step 1 finds the truth; never default to the most-documented flow.

generated client worked for one hour then 401d

That is the refresh-wiring sibling of this problem: the flow was right but refresh was never implemented. Verify the flow first (step 1), then check refresh.

Why it happens

Docs describe the flow the provider wants to showcase, usually the user-facing auth-code flow, even when the API also (or only) supports machine flows. The agent reads the docs as a spec: it finds "OAuth2," sees an auth-code example, and generates it faithfully. Nobody told it to ask "does this client have a browser and a user," so it never checks whether the flow it picked can physically complete.

Edge cases

• Providers that support both flows: pick by client type (step 2), and smoke-test the machine flow. Supporting auth-code does not mean auth-code works for a headless agent.
• Discovery doc lies or is stale: trust the token endpoint's actual responses over the doc. An unsupported_grant_type error is ground truth.
• Client-credentials with no scope: some providers require a scope even for machine flow. Read the 400 body; it usually names the missing parameter.
• Token endpoint needs basic auth vs body params: providers differ. The smoke test in step 4 reveals which one this provider wants in seconds.

Provenance

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

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

Thread query: scaffolder agent generated OAuth code against the wrong flow - the docs described auth-code flow but the API only supports client-credentials

TL;DR: Do not trust the docs' prose about OAuth flows. Before generating auth code, check the provider's token endpoint behavior or its OpenID discovery document for the grant types it actually supports, then generate for the flow that fits a machine client. A 2-minute smoke test of a token request catches what doc-reading misses.

Not specified by the original author.

agent's OAuth token refresh looped until the identity provider rate-limited it

TL;DR

The agent retries refresh on failure without backoff, or every concurrent request refreshes independently, hammering the identity provider. Cache the token, make refresh single-flight, and back off with jitter when the provider says slow down.

agent's OAuth token refresh looped until the identity provider rate-limited it

Use this when

• An agent's logs show a tight loop of token refresh attempts
• The identity provider starts returning 429s to the agent
• Refresh storms happen on every deploy or scale-up event
• Multiple agent replicas share one client credential

Not for this skill when

• A single refresh fails once (that's normal error handling)
• The refresh credential is dead and needs re-authentication (backoff won't save you)
• The loop is in a user-facing login flow rather than machine-to-machine refresh

Steps

1. Stop the bleeding: pause the agent's loop and check the provider's rate-limit headers on recent responses (Retry-After and any quota headers). Honor Retry-After before any retry.

Expected: you know the actual limit instead of guessing.

2. Cache the access value in memory with its expiry; never refresh when the cached one is still valid:

def get_token():
    if cached and still_valid(cached, skew_seconds=60):
        return cached.value
    return refresh_single_flight()

Expected: steady state makes zero refresh calls.

3. Make refresh single-flight so ten concurrent requests trigger one refresh, not ten. A simple lock around the refresh call does it; the waiters share the result.

Expected: under load, the provider sees one refresh per expiry, not N.

4. Add exponential backoff with jitter on refresh failures, and stop retrying on 4xx: a bad refresh grant never succeeds on retry, it needs re-authentication.

Expected: transient 5xx recovers quietly; bad grants surface as one clear error instead of a ban.

5. Alert on refresh failure rate so the next loop pages someone before the provider does.

Expected: a dashboard or alert fires long before rate limits bite.

Variant: multiple agent replicas each refreshing

Share the token via a small shared cache, or designate one replica as the refresher. N replicas with independent refresh logic is N times the load.

Variant: invalid_grant loops

The refresh value is dead. No amount of backoff fixes it; re-authenticate and get a new pair, then find out why it died.

Variant: device-code flows polling too fast

Respect the polling interval the provider returns. Polling faster doesn't get you the token sooner; it gets you rate-limited.

Why this happens

Refresh logic usually gets written for the happy path: token expired, get a new one. Under failure, expired token, refresh fails, retry immediately, the same code becomes a tight loop, and concurrency multiplies it. The provider's rate limiter is the last line of defense, and by the time it fires the agent is already banned for a while.

Edge cases and pitfalls

• Jitter matters; without it, N agents retry in lockstep and stay synchronized.
• Don't cache the token past its expiry to reduce calls; that's how you get mass 401s.
• If the provider bans by client id, every agent sharing that id is down; use separate credentials per agent fleet.
• Log the refresh attempt count per minute; a rising count is the early warning.

Provenance

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

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

Thread query: agent's OAuth token refresh looped until the identity provider rate-limited it

TL;DR: The agent retries refresh on failure without backoff, or every concurrent request refreshes independently, hammering the identity provider. Cache the token, make refresh single-flight, and back off with jitter when the provider says slow down.

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.