Document tri-state health checks, exact login error codes, and rejected-credential replacement

[masnwilliams]

Summary

Three customer-visible behavior changes are landing in managed auth that the docs currently describe incorrectly.

auth/connection-lifecycle.mdx

• The health-check step said a check either finds the session logged in or expired. It now reaches one of three conclusions, and the third one matters to users: an inconclusive check (challenge page, timeout, partial load) leaves the connection untouched and does not trigger reauth. Explains why that's deliberate — a spurious login can trip risk checks, prompt device verification, or invalidate a working session.
• "Kernel retries with exponential backoff" was wrong as a blanket statement. Retry now depends on the failure: transient site errors get one retry, conclusive rejections get none.
• Error table gains account_locked, rate_limited, and website_error, plus a Retried column and recovery steps for the new codes. account_locked specifically needs a "don't just call .login() again" note.

auth/programmatic.mdx

• New section for replace_existing, a new field on discovered_fields. When a site explicitly rejects a value, the flow returns to AWAITING_INPUT with that field flagged instead of failing the whole login, so the client should re-prompt rather than resubmit. Also states that unattended reauth fails with credentials_invalid instead of resubmitting, since repeated bad submissions are what lock accounts.

auth/faq.mdx

• Same retry correction, kept to one sentence.

Scope

replace_existing is already in openapi.yaml on the API change, so it will be in the generated SDKs. The rest is behavior description, no new surface.

Deliberately not included, because they aren't shipped yet: the canonical fields/choices awaiting-input contract (programmatic.mdx still documents discovered_fields / mfa_options / sign_in_options, which remain supported), the typed account-picker blocker, and any change to can_reauth semantics. Those need their own pass once the hosted client is released.

Ordering

Draft until the API change merges and deploys. Nothing here is true on production yet.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Error		Jul 31, 2026 7:57pm

[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.