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

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