auth: refresh managed auth docs for May 2026 changes

auth/faq.mdx

@@ -100,6 +100,8 @@ Managed Auth is designed for login and authentication flows — entering credent
 
 Go to the **Browser Sessions** tab in the Kernel dashboard to watch what the managed auth session is doing in real time. Each auth login runs in a browser session with a live view, so you can see exactly where the flow is getting stuck. This is useful for diagnosing login flow problems or understanding why a session isn't staying authenticated.
 
+For flakes that only show up intermittently or are hard to reproduce live, set `record_session: true` on the connection to capture a [replay](/browsers/replays) of every auth browser session — logins, periodic health checks, and automatic reauths. To record only a single login attempt without recording subsequent health checks and reauths, pass `record_session: true` on `.login()` instead. Recordings start automatically when each auth browser is created and stop when it's destroyed, the `replay_id` is persisted on each session, and recordings count toward your normal replay storage. See the [Hosted UI guide](/auth/hosted-ui#record-sessions-for-debugging) for examples.
+
 ## Can I attach multiple auth connections to one profile?
 
 Yes. A profile can have any number of auth connections, each for a different domain. When you create a browser with that profile, it is already logged in to every connected domain.

auth/hosted-ui.mdx

@@ -285,7 +285,48 @@ await kernel.auth.connections.update(
 ```
 </CodeGroup>
 
-You can update `login_url`, `credential`, `allowed_domains`, `health_check_interval`, `save_credentials`, and `proxy`. Only the fields you provide will be changed. Changes to `health_check_interval` and `proxy` take effect immediately on the running connection workflow.
+You can update `login_url`, `credential`, `allowed_domains`, `health_check_interval`, `save_credentials`, `record_session`, and `proxy`. Only the fields you provide will be changed. Changes to `health_check_interval` and `proxy` take effect immediately on the running connection workflow.
+
+### Record Sessions for Debugging
+
+Set `record_session: true` to capture a [replay](/browsers/replays) of every browser session tied to the connection — initial logins, background health checks, and automatic re-authentications. Recordings start automatically when each auth browser is created and stop when it's destroyed — no explicit stop call needed.
+
+<CodeGroup>
+```typescript TypeScript
+const auth = await kernel.auth.connections.create({
+  domain: 'example.com',
+  profile_name: 'my-profile',
+  record_session: true,
+});
+```
+
+```python Python
+auth = await kernel.auth.connections.create(
+    domain="example.com",
+    profile_name="my-profile",
+    record_session=True,
+)
+```
+</CodeGroup>
+
+You can also override the connection default for a single login by passing `record_session` on `.login()` — useful for one-off debugging on a specific login attempt without flipping the connection-wide flag (which would also record subsequent health checks and reauths).
+
+<CodeGroup>
+```typescript TypeScript
+const login = await kernel.auth.connections.login(auth.id, {
+  record_session: true,
+});
+```
+
+```python Python
+login = await kernel.auth.connections.login(
+    auth.id,
+    record_session=True,
+)
+```
+</CodeGroup>
+
+Recordings count toward your replay storage like any other browser replay. Each managed auth session row stores its own `replay_id` for the recording captured during that session.
 
 ### Post-Login URL
 

auth/overview.mdx

@@ -99,12 +99,17 @@ await page.goto("https://netflix.com")
 
 ## Choose Your Integration
 
-<CardGroup cols={2}>
+<CardGroup cols={3}>
   <Card title="Hosted UI" icon="browser" href="/auth/hosted-ui">
     **Start here** - Simplest integration
 
     Redirect users to Kernel's hosted page. Add features incrementally: save credentials for auto-reauth, custom login URLs, SSO support.
   </Card>
+  <Card title="React Component" icon="react" href="/auth/react">
+    **Embed in your app** - Drop-in component
+
+    Mount `<KernelManagedAuth />` on a route in your own app. Same flow as Hosted UI, rendered on your origin and trivial to restyle to match your brand.
+  </Card>
   <Card title="Programmatic" icon="code" href="/auth/programmatic">
     **Full control** - Custom UI or headless
 

auth/profiles.mdx

@@ -9,7 +9,7 @@ Profiles let you capture browser state created during a session (cookies and loc
 
 When you create a [Managed Auth connection](/auth/overview), it is attached to a profile. A single profile can hold multiple auth connections — one per domain — so a browser launched with that profile is logged in to all of them at once.
 
-You can also use profiles without Managed Auth. The first step in using profiles is to create one, optionally giving it a meaningful `name` that is unique within your organization.
+You can also use profiles without Managed Auth. The first step in using profiles is to create one, optionally giving it a meaningful `name` that is unique within your [project](/info/projects).
 
 <CodeGroup>
 ```typescript Typescript/Javascript
@@ -268,7 +268,7 @@ browser = await kernel.browsers.create(
 
 ## Notes
 
-- A profile's `name` must be unique within your organization.
+- A profile's `name` must be unique within your [project](/info/projects). The same name can be reused across different projects in the same org.
 - Profiles store cookies and local storage. Start the session with `save_changes: true` to write changes back when the browser is closed.
 - To keep a profile immutable for a run, omit `save_changes` (default) when creating the browser.
 - Multiple browsers in parallel can use the same profile, but only one browser should write (`save_changes: true`) to it at a time. Parallel browsers with `save_changes: true` may cause profile corruption and unpredictable behavior.

auth/programmatic.mdx

@@ -302,7 +302,7 @@ When the site offers multiple MFA methods, they appear in `mfa_options`:
 <CodeGroup>
 ```typescript TypeScript
 if (state.mfa_options?.length) {
-  // Available types: sms, email, totp, push, call, security_key
+  // Available types: sms, email, totp, push, call, password, switch
   for (const opt of state.mfa_options) {
     console.log(`${opt.type}: ${opt.label}`);
   }
@@ -316,7 +316,7 @@ if (state.mfa_options?.length) {
 
 ```python Python
 if state.mfa_options:
-    # Available types: sms, email, totp, push, call, security_key
+    # Available types: sms, email, totp, push, call, password, switch
     for opt in state.mfa_options:
         print(f"{opt['type']}: {opt['label']}")
 
@@ -330,6 +330,10 @@ if state.mfa_options:
 
 After selecting an MFA method, the flow continues. Poll for `discovered_fields` to submit the code, or handle external actions for push/security key.
 
+<Info>
+The `switch` type represents generic method-switcher links like "Use another method" or "Try another way" that don't name a specific factor. Submit it the same way as any other MFA option to reveal the underlying alternatives on the next page.
+</Info>
+
 ### Sign-In Options (Account/Org Pickers)
 
 Some sites present non-MFA choices during login, such as account selection or organization pickers. These appear in `sign_in_options` as an array of objects with `id`, `label`, and optional `description`:
@@ -380,8 +384,16 @@ if (state.flow_step === 'AWAITING_EXTERNAL_ACTION') {
   // Show the message to the user
   console.log(state.external_action_message);
   // e.g., "Check your phone for a push notification"
-
-  // Keep polling—the flow resumes automatically when the user completes the action
+
+  // Some sites offer fallback methods alongside the external action
+  // (e.g. "Try another way"). Submit one to switch verification methods.
+  if (state.mfa_options?.length) {
+    await kernel.auth.connections.submit(auth.id, {
+      mfa_option_id: state.mfa_options[0].type,
+    });
+  }
+
+  // Otherwise keep polling—the flow resumes automatically when the user completes the action
 }
 ```
 
@@ -390,11 +402,23 @@ if state.flow_step == "AWAITING_EXTERNAL_ACTION":
     # Show the message to the user
     print(state.external_action_message)
     # e.g., "Check your phone for a push notification"
-
-    # Keep polling—the flow resumes automatically when the user completes the action
+
+    # Some sites offer fallback methods alongside the external action
+    # (e.g. "Try another way"). Submit one to switch verification methods.
+    if state.mfa_options:
+        await kernel.auth.connections.submit(
+            auth.id,
+            mfa_option_id=state.mfa_options[0]["type"],
+        )
+
+    # Otherwise keep polling—the flow resumes automatically when the user completes the action
 ```
 </CodeGroup>
 
+<Info>
+`mfa_options`, `pending_sso_buttons`, and `sign_in_options` may be populated during `AWAITING_EXTERNAL_ACTION` when the site exposes fallback methods alongside the external action (for example, "Try another way" on a push prompt). Submit one of them to switch verification methods, or keep polling to let the user complete the external action.
+</Info>
+
 ## Step Reference
 
 The `flow_step` field indicates what the flow is waiting for:
@@ -437,6 +461,7 @@ After creating a connection, you can update its configuration with `PATCH /auth/
 | `allowed_domains` | Update allowed redirect domains |
 | `health_check_interval` | Seconds between health checks (minimum varies by plan) |
 | `save_credentials` | Whether to save credentials on successful login |
+| `record_session` | Record a [replay](/browsers/replays) of every auth browser session for this connection (logins, health checks, and reauths) |
 | `proxy` | Proxy configuration for login sessions |
 
 Only the fields you include are updated—everything else stays the same.