docs(auth): scope=commerce selects the commerce consent; the authorization response carries RFC 9207 iss

[r-marques]

Companion to nevermined-io/nvm-monorepo#3532 (implements nevermined-io/nvm-monorepo#3527, part of epic nevermined-io/nvm-monorepo#3458 — ADR 0077). Documents two AS-side behaviours that PR ships; merge after it deploys so the docs never lead the API.

What changed

• integrate/authentication/overview.mdx — the RFC 8414 example gains authorization_response_iss_parameter_supported: true, and a new section The authorization response names its issuer (RFC 9207): iss on the ?code= success and the ?error= denial alike, equal to the tier's issuer, compare by plain string equality and reject a mismatch; the device flow has no authorization response.
• integrate/authentication/oauth-authorization-code.mdx — a prerequisite on which consent you are asking for: agent_id → agent-specific; otherwise account-level, consent_type=commerce for a hand-configured provider (LangSmith Fleet keeps its ?consent_type=commerce), scope=commerce for a discovery-driven client that never saw consent_type; an explicit consent_type wins; consent_type=account_access&scope=commerce or scope=commerce + agent_id is refused, never guessed; scope is not advertised (no scopes_supported, unchanged) and never reaches the API. iss on the hand-off, and the flag in the discovery note.
• integrate/authentication/for-agents.mdx — the two extra facts the document tells an agent (iss; scope=commerce as the one scope the consent screen honours).
• integrations/mcp.mdx — a note on consent selection through scope (MCP clients forward the scope from the server's WWW-Authenticate challenge) and on iss, including why ChatGPT cares (stable CIMD client identity).
• api-reference/oauth-openapi.json (hand-maintained, per the docs CLAUDE.md exception) — the flag in the description and the example, edited as text.

Deliberately not touched: products/catalog/mcp.mdx's "OAuth-connector variant … tracked elsewhere" — that is the Commerce MCP's own challenge/PRM (nvm-monorepo#3459) and the verification matrix (#3460), documented when those land. api-reference/** SDK-sourced trees untouched.

Verification

mintlify broken-links → success no broken links found (run from a worktree off origin/main; no bare <placeholder> in the diff, so the check did run).

🤖 Generated with Claude Code

---

2026-09-21 — out of draft. Production is enabled and in effect (argocd#646 merged + synced; connect/details → ["commerce"] on both prod tiers), so the gate these drafts waited on is met. Stacked PR: base = main; #409 → #411 → #414 follow. Rebased onto the current pages (main restructured for-agents.mdx / overview.mdx and grew mcp.mdx meanwhile); mintlify broken-links green. Merge in order — GitHub retargets each base to main as the previous one lands.

[aaitor]

No description provided.

[aaitor]

Reviewed the current head. One documentation consistency issue is inline.

[aaitor]

No description provided.

[aaitor]

Re-review at 26240577. My 09-15 should-fix (oauth-authorization-code.mdx:24, "always wins") is folded — the new wording ("kept as long as scope does not contradict it; a contradiction … is refused") matches selectConsentType exactly, so that thread can be resolved.

I re-checked the behavioural claims against nvm-monorepo main: selectConsentType (oauth-scope.ts: contradiction and agent_id both throw, extra scope tokens ignored), iss on the success redirect, on denial (access_denied) and on the authorize error card (buildOAuthCallbackUrl / buildOAuthErrorUrl), issuer = origin of the tier's backendUrl, authorization_response_iss_parameter_supported in the RFC 8414 document, no iss on the device flow, and the #prerequisites anchor. Both OpenAPI JSON files parse. Nothing blocks; one nit inline.

[aaitor]

🟡 Approved with comments — no blockers; 0 should-fix, 1 nit(s) left inline.

Inline review: #404 (review)