Document canonical managed auth interactions

[masnwilliams]

summary

• replace legacy managed-auth input arrays with canonical interaction_id, fields, and choices
• document field_values, selected_choice_id, stable choice identity, and rejected fields via fields[].reason
• update partial-credential examples across TypeScript, Python, and Go
• document tri-state health checks and exact failure/retry behavior

validation

• rendered the programmatic flow, connection lifecycle, FAQ, and credentials pages with mintlify dev
• checked all managed-auth docs for legacy input and submit properties
• git diff --check origin/main...HEAD

---

Note

Low Risk
Documentation-only changes to Managed Auth guides and examples; no runtime code or API behavior changes in this diff.

Overview
Managed Auth docs now describe the canonical interaction model instead of legacy SSE/submit shapes (discovered_fields, per-type submit params like mfa_option_id / sign_in_option_id / SSO selectors).

The programmatic flow guide is rewritten around interaction_id, fields, and choices, with submissions via field_values (keys are field ids) or selected_choice_id. It adds the interaction contract, rejected-field handling (reason: 'rejected'), unified choices (MFA, SSO, account/org pickers), and shorter external-action guidance. Credentials partial-login examples in TypeScript, Python, and Go are updated to match.

Connection lifecycle and FAQ now document tri-state health checks (logged in / definitely logged out / inconclusive), auto-reauth only on definite logout, refined can_reauth wording, and selective login retries (not blanket exponential backoff) with an expanded error-code table and recovery notes (account_locked, rate_limited, website_error, in-place credential replacement).

^{Reviewed by Cursor Bugbot for commit 939b951. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Error		Aug 10, 2026 7:37pm

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	Jul 31, 2026, 7:57 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[masnwilliams]

Checked whether any of this needs executor qualification (CUA-Go vs the CUA-TS executor we're migrating to). It doesn't, and that's deliberate rather than an oversight:

• All four customer-visible changes here — tri-state health checks, exact terminal error codes, the bounded website_error retry, and replace_existing — apply to both executors. Verification in particular runs the same Go verifier regardless of executor.
• The CUA-TS-only changes (configured-SSO auto-selection, auth-check URL provenance, the bounded page_state contract) have no public API surface, so they don't belong on these pages.
• The legacy ODA executor doesn't get these, but CUA is at 100% rollout, so it isn't serving new logins.

So the contract stays uniform: a caller shouldn't be able to tell which executor ran their login from the error codes or the awaiting-input shape. Executor identity is an internal implementation detail and is documented as such in the engineering README instead.

Vercel is red here, but it's red on the four PRs before this one too — pre-existing. Mintlify deploy and broken-links both pass.

[masnwilliams]

Holding this in draft on one dependency I re-verified today.

The "replacing a rejected credential" example filters discovered_fields for replace_existing. That flag currently reaches the canonical fields projection only — mapPendingFields drops it, and DiscoveredField has no such property — so the example returns nothing today for every client reading discovered_fields, which is the shape these docs describe. kernel/kernel#3094 forwards it to the legacy projection on both the REST read path and the SSE managed_auth_state event.

So: merge this after kernel/kernel#3094, not just after the verification PR. The other three changes here (tri-state health checks, exact terminal error codes, conditional retry) are live on main as of kernel/kernel#3021 and are accurate now.

[cursor]

Stale comment

Risk assessment: Very Low

Verdict: Very Low risk. Prior approval from this automation remains in effect (not re-approved).

This is a re-evaluation after the PR was updated (fff62b0 → 7a7c85a). Risk did not increase, so approval is not revoked.

Evidence (from diff only)

• Files changed (4): auth/connection-lifecycle.mdx, auth/credentials.mdx, auth/faq.mdx, auth/programmatic.mdx
• Diff size: +242 / −606
• Change type: Documentation-only MDX updates (health-check / retry / error-code copy, and a rewrite of the programmatic login contract examples)

What changed since the last assessment

The previously approved head was a small 3-file docs tweak (+52 / −11). The new commit adds auth/credentials.mdx example updates and a large rewrite of auth/programmatic.mdx. Scope is still published docs only.

Why Very Low

• No application code, infra, CI, config, schema, or runtime logic changes
• No shared systems or production auth implementation modified
• Blast radius limited to Mintlify documentation pages
• No CODEOWNERS file; branch ruleset does not require code-owner review

Re-approval note

This automation already approved commit fff62b0. Because risk remains Very Low, that approval is left in place and is not repeated.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk assessment: Very Low

Verdict: Very Low. Existing approval remains in effect (not re-approved).

Re-evaluated the current HEAD (7a7c85a) from the file diff only. Risk did not increase, so approval is not revoked.

Evidence (from diff only)

• Files changed (4): auth/connection-lifecycle.mdx, auth/credentials.mdx, auth/faq.mdx, auth/programmatic.mdx
• Diff size: +242 / −606
• Change type: Mintlify MDX documentation only — health-check / retry / error-code copy, FAQ wording, and a rewrite of programmatic login examples to the interaction_id + field_values / selected_choice_id contract

Why Very Low

• No application code, CI, config, schema, OpenAPI, or runtime logic changes
• No shared systems or production auth implementation modified
• Blast radius is published documentation pages only
• No CODEOWNERS file; the main ruleset has require_code_owner_review: false

Approval

reviewDecision is already APPROVED. Per policy this run does not approve again.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk assessment: Very Low

Verdict: Very Low. Existing approval remains in effect (not re-approved).

Re-evaluated current HEAD (697f785) from the file diff only. Risk did not increase versus the prior assessment, so approval is not revoked.

Evidence (from diff only)

• Files changed (4): auth/connection-lifecycle.mdx, auth/credentials.mdx, auth/faq.mdx, auth/programmatic.mdx
• Diff size: +240 / −636
• Change type: Mintlify MDX documentation only — health-check / retry / error-code copy, FAQ wording, credential example updates, and a rewrite of programmatic login examples to the interaction_id + field_values / selected_choice_id contract

What changed since the last assessment

HEAD moved from 7a7c85a to 697f785 (rewritten commit; same 4 files). Scope is still published docs only — no new paths, config, CI, or runtime files.

Why Very Low

• No application code, CI, config, schema, OpenAPI, or runtime logic changes
• No shared systems or production auth implementation modified
• Blast radius is published documentation pages only
• No CODEOWNERS file; the main ruleset has require_code_owner_review: false

Approval

reviewDecision is already APPROVED. Per policy this run does not approve again.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk assessment: Very Low

Verdict: Very Low. Existing approval remains in effect (not re-approved).

Re-evaluated current HEAD (939b951) from the file diff only. Risk did not increase versus the prior assessment, so approval is not revoked.

Evidence (from diff only)

• Files changed (4): auth/connection-lifecycle.mdx, auth/credentials.mdx, auth/faq.mdx, auth/programmatic.mdx
• Diff size: +245 / −637
• Change type: Mintlify MDX documentation only — health-check / retry / error-code copy, FAQ wording, credential example updates, and a rewrite of programmatic login examples to the interaction_id + field_values / selected_choice_id contract

What changed since the last assessment

HEAD moved from 697f785 to 939b951 (Clarify managed auth compatibility). Incremental scope is 2 files, +8 / −4: wording on can_reauth and credentials_invalid recovery, plus a managed_auth_state event-type guard in the TypeScript stream example. No new paths, config, CI, or runtime files.

Why Very Low

• No application code, CI, config, schema, OpenAPI, or runtime logic changes
• No shared systems or production auth implementation modified
• Blast radius is published documentation pages only
• No CODEOWNERS file; the main ruleset has require_code_owner_review: false

Approval

reviewDecision is already APPROVED. Per policy this run does not approve again.

  

_{Sent by Cursor Automation: Assign PR reviewers}