docs(auth): OAuth callback identity verification

[Anshu Garg (anshugarg15)]

Summary

Documents OAuth callback identity verification — the opt-in, per-project verifier that confirms which user an OAuth connection belongs to before it activates (source: platform PR ComposioHQ/platform#11189).

• Changelog content/changelog/07-17-26-oauth-callback-identity-verification.mdx — why it exists, the flow, a cURL example for complete_auth, and an opt-in / no-action-required callout. Modeled on 02-06-26-webhook-subscriptions-api (new capability + public endpoint) and 04-09-26-multi-account-aliases (opt-in phrasing).
• Guide content/docs/oauth-callback-identity-verification.mdx — full flow, the security rationale, how to complete a verification, response handling, and the operational requirement that the completing browser be authenticated by your app so you can assert the right user_id. Filed under "Customizing auth", after white-labeling-authentication.
• Nav — registered in content/docs/meta.json.
• Companion — cross-link Card added to white-labeling-authentication.mdx (the page where callback routing is configured).

Every code reference is verified against platform source: complete_auth is POST /api/v3.1/connected_accounts/complete_auth, public (API_DOCS + SDK, project API key), request { session_uri, user_id }, and the response is the standard connected-account object.

Hold before merge — this is a draft

• The feature is not GA. Source PR #11189 is not merged; do not publish until it ships.
• Ship date is a placeholder. Filename 07-17-26 / frontmatter 2026-07-17 must be reset to the real ship date at merge.
• Enabling is not a public API. oauthCallbackVerifierUrl is set only via a dashboard-internal route (cloud, admin role) or a self-hosted cookie route — there is no project-API-key way to turn it on, and no SDK method. The docs therefore describe enabling as a per-project setting, not an API call. Confirm the exact enable UX (dashboard control) before GA — that's the one part written at concept altitude rather than click-level.
• complete_auth is not yet in the generated API reference, so it's documented inline with cURL (no /reference/... link, which would fail link validation). Add the API-ref link once the OpenAPI spec regenerates post-merge.

Validation

Ran the docs CI equivalents locally from docs/: lint:links (0 errors), static tests (33 pass / 0 fail), types:check (frontmatter schema + tsc clean). Production build not run locally (no ts code blocks in these files, so Twoslash has nothing to check); CI runs the full build.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 17, 2026 10:03am

[claude]

Claude finished Anshu Garg (@anshugarg15)'s task in 1m 27s —— View job

---

Docs review — Looks good ✅

Reviewed against docs-reviewer.md. The lens is "would a developer copying this get stuck or be misled?" — I found nothing blocking.

Checklist

• Read docs-reviewer.md criteria
• Ran git diff origin/next...HEAD
• Verified icon, nav, cross-links, API conventions

Verified

Check	Result
ShieldCheck icon (new Card in white-labeling-authentication.mdx)	✅ Imported + registered in mdx-components.tsx:53,153 — globally available, same as existing <Key />
Nav entry (meta.json)	✅ Added under ---Customizing auth---, right after white-labeling-authentication; file parses as valid JSON
Cross-links resolve	✅ /docs/white-labeling-authentication, /docs/manually-authenticating, and /docs/oauth-callback-identity-verification all exist
API base URL / auth header	✅ https://backend.composio.dev/api/v3.1/... + x-api-key match existing cURL docs (custom-oauth-webhooks.mdx, programmatic-auth-configs.mdx)
Changelog frontmatter	✅ title + date: '2026-07-17' (YYYY-MM-DD) present
Internal consistency	✅ complete_auth request { session_uri, user_id }, connected_account response shape, and the 400/404/200 semantics are stated identically in changelog and guide

One observation (non-blocking, already acknowledged in the PR description)

The "Enabling verification" section describes turning the feature on at concept altitude rather than click-level — there's no copy-paste step. Per docs-reviewer.md this would normally read as a "missing step," but it's the correct call here: you've documented that enabling is not a public API (dashboard-internal / self-hosted cookie route only), so there's no interface a developer could get stuck on. Worth resolving to click-level UX before GA, as your description notes.

On the merge holds: I'm not treating the draft/GA caveats (unmerged platform PR #11189, placeholder ship date 07-17-26, missing /reference/... link for complete_auth) as review findings — they're release-gating items you've already flagged, not doc defects. Just make sure the filename/date get reset to the real ship date and the API-ref link is added once the OpenAPI spec regenerates.

Content is accurate, self-consistent, well cross-linked, and CI-clean per your local runs. Ship it once the feature is GA.