Document managed auth verification before tasks

[AnnaXWang]

summary

• recommend calling .login() immediately before authenticated work
• document waiting for the connection stream to reach SUCCESS before creating a profile-backed browser
• clarify why cached connection status alone cannot guarantee the website session is still active

validation

• npx -y mint@4.2.930 broken-links
• rendered /auth/connection-lifecycle and /auth/faq locally and verified HTTP 200 responses

---

Note

Low Risk
Documentation-only changes to auth guides; no runtime or API behavior changes.

Overview
Docs now recommend verifying auth immediately before authenticated work instead of framing .login() mainly as manual re-auth ahead of the next health check.

The Connection Lifecycle section is retitled to Verify authentication before starting work and explains that connection status only reflects the last health check, that .login() can verify an existing session first when an auth check URL exists, and that callers should follow the connection stream until SUCCESS before creating a profile-backed browser. It adds end-to-end ensureAuthenticated examples (TypeScript, Python, Go) that handle AWAITING_INPUT / AWAITING_EXTERNAL_ACTION via hosted_url without calling .login() again.

The FAQ renames the related question and points to the new anchor with the same pre-task verification guidance.

^{Reviewed by Cursor Bugbot for commit dab983d. 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
Kernel	🟢 Ready	View Preview	Oct 6, 2026, 4:42 PM

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

[masnwilliams]

lgtm, one note on framing: worth saying up front that this is a pre-task auth check, not a replacement for the normal login flow. .login() first checks whether the profile is still signed in, and if it is, it reaches SUCCESS without submitting anything. if it isn't, kernel logs in again with the saved credentials. if that needs the user (MFA, missing credentials, a captcha), the flow pauses on AWAITING_INPUT/AWAITING_EXTERNAL_ACTION, and at that point you're back to the regular login flow: send the user to the hosted_url from this .login() call. don't call .login() again, because that cancels the flow in progress. the samples should stop at that point and return or throw with hosted_url instead of following the stream until it expires.

[AnnaXWang]

addressed the pre-task framing and fallback behavior:

• clarified that the verifier runs first only when the connection has a previous successful login and saved auth check URL
• stop immediately on AWAITING_INPUT or AWAITING_EXTERNAL_ACTION and surface the original call's hosted_url
• warn not to call .login() again because it cancels the active flow

updated the TypeScript, Python, and Go samples and re-ran the docs checks.

[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 dab983d. Configure here.}

[cursor]

Auth-check URL is executor-internal

Medium Severity

The new copy gates verifier-first .login() behavior on a saved auth check URL and names the verifier. That artifact and component are CUA-TS internals, not part of the public connection contract, so readers cannot observe or configure them.

Additional Locations (1)

• auth/faq.mdx#L38-L39

 

^{Triggered by learned rule: Managed Auth docs use the canonical interaction model}

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

[cursor]

FAQ restates lifecycle guidance

Low Severity

The FAQ answer now restates verifier-first behavior, hosted_url handoff, and the warning not to call .login() again, which already live on the lifecycle page, instead of a short pointer plus link.

 

^{Triggered by learned rule: Single source of truth — no deep content duplication across pages}

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