clarify managed auth reauthentication scope

[akxue]

context

managed auth documentation currently places automatic reauthentication beside broader interactive login capabilities without consistently defining the automatic path. several pages also describe saved profile state as a guaranteed active login.

this can imply that every supported interactive login can run again unattended. the product promise is narrower: automatic reauthentication covers credential-only flows and attempts to provide totp codes when needed.

changes

• define the automatic reauthentication promise consistently across managed auth overview, setup, lifecycle, credential, integration, pricing, and cli docs
• offer a general support path for readers who want help using managed auth
• distinguish reusable profile state from a guarantee that every saved session is still active
• document can_reauth as eligibility to attempt reauthentication and link can_reauth_reason as the canonical explanation
• retain self-service recovery guidance for passkey-only flows and configuration guidance for custom sso providers
• document the existing cli flags and their mutually exclusive pairs
• match the sentence casing and voice of the surrounding docs

alternatives considered

a mechanism-by-mechanism public limitations matrix would be more exhaustive, but it would repeat implementation details across customer-facing pages and lead with unsupported cases. this change keeps the public promise specific and offers support for readers who want help using managed auth.

testing and validation

• ran mint broken-links
• rendered the docs with mint dev --port 3005 and verified the affected routes returned 200
• verified the absolute can_reauth_reason api reference link resolves successfully
• ran git diff --check
• proofread the full diff for factual scope, readability, consistency, and surrounding docs style
• ran spelling and prose-style scans; reviewed expected product and technical term findings manually

---

Note

Low Risk
Documentation-only wording and CLI flag reference updates; no runtime or API behavior changes in this diff.

Overview
This PR tightens Managed Auth docs so automatic reauthentication is described as a narrow, credential-based capability (plus TOTP when Kernel can supply codes), not as a blanket guarantee that every interactive login can run unattended again.

Across overview, configuration, lifecycle, credentials, hosted UI, programmatic, profiles, FAQ, 1Password, pricing, browser pools/FAQ, and CLI reference, copy now consistently says Kernel may reauthenticate eligible flows, distinguishes saved profile authentication state from “always logged in,” and softens absolutes on SSO/OAuth and site coverage.

Connection lifecycle updates are the deepest: can_reauth is framed as eligibility to attempt (with a prior successful login, linked credentials, and no blocking requirement), can_reauth_reason is linked to the API reference, and recovery guidance for flows needing human input is reframed without implying unattended replay.

CLI docs newly document --no-health-checks / --no-auto-reauth on connections create and the --health-checks / --auto-reauth toggle pairs on connections update.

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

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	Sep 3, 2026, 6:21 AM

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

[cursor]

Stale comment

Risk assessment: Very Low

Re-evaluated after ready_for_review. Head commit is still a2b420d. Risk is unchanged.

Approval stands. This automation already approved that commit. No re-approval and no dismissal.

Evidence (diff only)

• 15 .mdx files, 91 insertions / 80 deletions. All are Mintlify documentation pages.
• No application code, docs.json, workflows, CI, OpenAPI, or infrastructure files.
• No CODEOWNERS file in the repo, so codeowner review is not required.

Wording updates only:

• Narrows automatic reauthentication copy to stored credentials, or stored credentials plus a saved TOTP secret.
• Replaces “already logged in” with “loads saved authentication state.”
• Adds CLI flag rows on the Managed Auth CLI reference page.
• Softens FAQ / overview product claims (including removing the explicit passkey warning) in favor of scoped reauth language and support pointers.

Why Very Low

• Documentation-only; no production logic, auth implementation, billing, or permission changes.
• No shared services or infra impact.
• Blast radius is public docs copy. Incorrect claims would be a docs accuracy issue, not a runtime one.
• These pages are customer-facing docs, not model instruction / prompt files.

Risk did not increase. Prior approval remains in effect.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[masnwilliams]

went through this — overall the direction is right. we were implying that every interactive login can replay unattended, and narrowing that is overdue.

my main reaction is that a couple of the specifics narrow past what we actually ship today, and the one field we tell people to read is described a bit differently than the api computes it. flagged those inline. the rest of the diff reads well to me and i'd leave it alone.

two worth pulling up here:

the totp framing. #529 moved this off "the credential has no totp secret" on purpose. can_reauth comes back true for a totp flow whether or not a secret is stored, and we do attempt the reauth — that optimism is deliberate. this pr reintroduces secret-presence as the headline promise in ~8 places, so it under-describes what the product actually does. suggest reusing #529's wording.

can_reauth_reason. we already return a typed reason alongside can_reauth, with a value per outcome, split into "reauth is possible" and "a human has to finish the login" — it's in the api reference, and the dashboard already maps each one to a human-readable explanation. documenting that is both more accurate than the matrix and means we don't hand-maintain a second description of the same policy that can drift. fine as a follow-up if you'd rather not expand this pr.

none of this is blocking imo, i just want the claims to match current behavior before it ships.

[masnwilliams]

Automatic reauthentication depends on the provider's login requirements.

is there anywhere we can link to here, like a place that shows how we decide if a connection can/cannot review

[masnwilliams]

can_reauth is true for a totp flow regardless of whether a secret is stored, and we'll go ahead and attempt the reauth — that's intentional, not a gap. #529 changed this exact wording four days ago for the same reason.

suggest matching it: the outcome is "an authenticator code kernel couldn't provide automatically", not "no secret saved". the same sentence shows up in ~7 other files in this diff, so worth doing in one pass.

[masnwilliams]

two things on this line.

can_reauth also requires a prior successful login — that's the most common reason it comes back false on a fresh connection, and we don't document it anywhere today.

and the table below reads as this boolean's semantics when it's really describing whether reauth will succeed. those come apart (see the totp row). worth stating that can_reauth is eligibility to attempt, not a success prediction.

[masnwilliams]

an account picker blocks unattended reauth but isn't really "verification or approval" — we surface it as account_choice_required, and it's in the error table further down this page. the old text's "or other external action" at least caught it.

[masnwilliams]

i'd keep the passkey line here. unsupported_auth_method is a code we return today for passkey-only logins, and it's already in the error table on the lifecycle page with the recovery step.

pointing at that is more useful than routing to support — this is the exact thing people hit when a google account has passkeys turned on, and it's answerable without us.

[masnwilliams]

"with support for custom providers" reads like a custom provider works out of the box — its domain would still need adding to allowed_domains, only the common ones are allowed by default.

also the bullet doesn't say sso actually works anymore, just that domains are allowlisted.

[masnwilliams]

--auto-reauth and --no-auto-reauth are mutually exclusive — passing both errors out, same for the health-check pair. worth a note since both rows sit next to each other.

minor, but the two rows also describe the same flag from different angles ("for eligible flows" vs "after an expired session is detected").

[cursor]

Stale comment

Risk assessment: Very Low

Re-evaluated after synchronize. Head is now 3d6ea2b (previously approved commit was a2b420d).

Risk is unchanged. Approval stands. This automation already approved the PR. No re-approval and no dismissal.

Evidence (diff only)

• 15 .mdx files, 92 insertions / 77 deletions. All are Mintlify documentation pages.
• No application code, docs.json, workflows, CI, OpenAPI, or infrastructure files.
• No CODEOWNERS file in the repo, so codeowner review is not required.

Wording updates only:

• Narrows automatic reauthentication copy to credential-only flows, with TOTP attempted when Kernel can supply a code.
• Treats can_reauth as eligibility to attempt reauth and points to can_reauth_reason.
• Replaces “already logged in” with “loads saved authentication state.”
• Documents existing CLI flags (--no-health-checks, --no-auto-reauth, and the matching enable/disable pairs) plus mutual exclusivity.
• Softens product claims and routes additional auth requirements to support. Passkey-only remains documented as unsupported.

Why Very Low

• Documentation-only; no production logic, auth implementation, billing, or permission changes.
• No shared services or infra impact.
• Blast radius is public docs copy. Incorrect claims would be a docs accuracy issue, not a runtime one.
• These pages are customer-facing docs, not model instruction / prompt files.

Risk did not increase. Prior approval remains in effect.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 3d6ea2b. Configure here.}

[cursor]

Stale comment

Risk assessment: Very Low

Re-evaluated after synchronize. Head is now d7d6f14 (previously approved commit was a2b420d; last assessed head was 3d6ea2b).

Risk is unchanged. Approval stands. This automation already approved the PR. No re-approval and no dismissal.

Evidence (diff only)

• 15 .mdx files, 108 insertions / 77 deletions. All are Mintlify documentation pages.
• Incremental change since last assessment: 8 .mdx files, 28 insertions / 12 deletions of wording only.
• No application code, docs.json, workflows, CI, OpenAPI, or infrastructure files.
• No CODEOWNERS file in the repo, so codeowner review is not required.

Wording updates only:

• Narrows automatic reauthentication copy to credential-only flows, with TOTP attempted when Kernel can supply a code.
• Treats can_reauth as eligibility to attempt reauth and points to can_reauth_reason via an absolute API reference URL.
• Replaces “already logged in” with “loads saved authentication state.”
• Documents existing CLI flags (--no-health-checks, --no-auto-reauth, and the matching enable/disable pairs) plus mutual exclusivity.
• Softens product claims. Passkey-only remains documented as unsupported, with a self-service recovery path. Support links are general “learn more” pointers, not a change to product behavior.

Why Very Low

• Documentation-only; no production logic, auth implementation, billing, or permission changes.
• No shared services or infra impact.
• Blast radius is public docs copy. Incorrect claims would be a docs accuracy issue, not a runtime one.
• These pages are customer-facing docs, not model instruction / prompt files.

Risk did not increase. Prior approval remains in effect.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk assessment: Very Low

Re-evaluated after synchronize. Head is now d83ec69 (previously approved commit was a2b420d; last assessed head was d7d6f14).

Risk is unchanged. Approval stands. This automation already approved the PR. No re-approval and no dismissal.

Evidence (diff only)

• 14 .mdx files, 95 insertions / 76 deletions. All are Mintlify documentation pages.
• Incremental change since last assessment: 9 .mdx files, 15 insertions / 27 deletions of wording only. index.mdx is no longer in the PR (reverted to main).
• No application code, docs.json, workflows, CI, OpenAPI, or infrastructure files.
• No CODEOWNERS file in the repo, so codeowner review is not required.

Wording updates only:

• Narrows automatic reauthentication copy to credential-only flows, with TOTP attempted when Kernel can supply a code.
• Treats can_reauth as eligibility to attempt reauth and points to can_reauth_reason via an absolute API reference URL.
• Replaces “already logged in” with “loads saved authentication state.”
• Documents existing CLI flags (--no-health-checks, --no-auto-reauth, and the matching enable/disable pairs on one row each).
• Softens product claims. Passkey-only remains documented as unsupported, with a self-service recovery path. Several support links were removed in this update.

Why Very Low

• Documentation-only; no production logic, auth implementation, billing, or permission changes.
• No shared services or infra impact.
• Blast radius is public docs copy. Incorrect claims would be a docs accuracy issue, not a runtime one.
• These pages are customer-facing docs, not model instruction / prompt files.

Risk did not increase. Prior approval remains in effect.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk assessment: Very Low

Re-evaluated after synchronize. Head is now 412bb9e (previously approved commit was a2b420d; last assessed head was d83ec69). History was rewritten; the current tree vs main is still documentation-only.

Risk is unchanged. Approval stands. This automation already approved the PR. No re-approval and no dismissal.

Evidence (diff only)

• 14 .mdx files, 95 insertions / 76 deletions. All are Mintlify documentation pages.
• No application code, docs.json, workflows, CI, OpenAPI, or infrastructure files.
• No CODEOWNERS file in the repo, so codeowner review is not required.

Wording updates only:

• Narrows automatic reauthentication copy to credential-only flows, with TOTP attempted when Kernel can supply a code.
• Treats can_reauth as eligibility to attempt reauth and points to can_reauth_reason via an absolute API reference URL.
• Replaces “already logged in” with “loads saved authentication state.”
• Documents existing CLI flags (--no-health-checks, --no-auto-reauth, and the matching enable/disable pairs on one row each).
• Softens product claims. Passkey-only remains documented as unsupported, with a self-service recovery path.

Why Very Low

• Documentation-only; no production logic, auth implementation, billing, or permission changes.
• No shared services or infra impact.
• Blast radius is public docs copy. Incorrect claims would be a docs accuracy issue, not a runtime one.
• These pages are customer-facing docs, not model instruction / prompt files.

Risk did not increase. Prior approval remains in effect.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk assessment: Very Low

Re-evaluated after synchronize. Head is now e51bb62 (previously approved commit was a2b420d; last assessed head was 412bb9e).

Risk is unchanged. Approval stands. This automation already approved the PR. No re-approval and no dismissal.

Evidence (diff only)

• 14 .mdx files, 89 insertions / 76 deletions. All are Mintlify documentation pages.
• Incremental change since last assessment: 3 .mdx files, 6 deletions. Removed three "contact support" sentences from auth/credentials.mdx, auth/faq.mdx, and auth/hosted-ui.mdx.
• No application code, docs.json, workflows, CI, OpenAPI, or infrastructure files.
• No CODEOWNERS file in the repo, so codeowner review is not required.

Wording updates only:

• Narrows automatic reauthentication copy to credential-only flows, with TOTP attempted when Kernel can supply a code.
• Treats can_reauth as eligibility to attempt reauth and points to can_reauth_reason via an absolute API reference URL.
• Replaces “already logged in” with “loads saved authentication state.”
• Documents existing CLI flags (--no-health-checks, --no-auto-reauth, and the matching enable/disable pairs on one row each).
• Softens product claims. Passkey-only remains documented as unsupported, with a self-service recovery path.

Why Very Low

• Documentation-only; no production logic, auth implementation, billing, or permission changes.
• No shared services or infra impact.
• Blast radius is public docs copy. Incorrect claims would be a docs accuracy issue, not a runtime one.
• These pages are customer-facing docs, not model instruction / prompt files.

Risk did not increase. Prior approval remains in effect.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk assessment: Very Low

Re-evaluated after synchronize. Head is now df5f289 (previously approved commit was a2b420d; last assessed head was e51bb62).

Risk is unchanged. Approval stands. This automation already approved the PR. No re-approval and no dismissal.

Evidence (diff only)

• 14 .mdx files, 92 insertions / 79 deletions. All are Mintlify documentation pages.
• Incremental change since last assessment: 5 .mdx files, comment/copy wording only (example comments, FAQ/overview/create sentences).
• No application code, docs.json, workflows, CI, OpenAPI, or infrastructure files.
• No CODEOWNERS file in the repository, so codeowner review is not required.
• These pages are product docs, not LLM instruction or system-prompt files.

Why Very Low

Documentation-only wording updates that narrow Managed Auth reauthentication claims and document existing CLI flags. No production logic, auth implementation, or shared-system changes.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk assessment: Very Low

Re-evaluated after synchronize. Head is now d02d4f6 (previously approved commit was a2b420d; last assessed head was df5f289). History was rewritten; the current tree vs main is still documentation-only.

Risk is unchanged. Approval stands. This automation already approved the PR. No re-approval and no dismissal.

Evidence (diff only)

• 14 .mdx files, 92 insertions / 79 deletions. All are Mintlify documentation pages.
• Incremental change since last assessment: 5 .mdx files, comment/copy wording only (auth/credentials.mdx, auth/faq.mdx, auth/overview.mdx, browsers/faq.mdx, introduction/create.mdx).
• No application code, docs.json, workflows, CI, OpenAPI, or infrastructure files.
• No CODEOWNERS file in the repository, so codeowner review is not required.
• These pages are product docs, not LLM instruction or system-prompt files.

Why Very Low

Documentation-only wording updates that narrow Managed Auth reauthentication claims and document existing CLI flags. No production logic, auth implementation, or shared-system changes.

  

_{Sent by Cursor Automation: Assign PR reviewers}