From 42bd077d227ac70212e3002d403c8cefe6d4cc8e Mon Sep 17 00:00:00 2001 From: masnwilliams <43387599+masnwilliams@users.noreply.github.com> Date: Tue, 24 Mar 2026 02:26:28 +0000 Subject: [PATCH 1/3] Update managed auth docs for CUA support, PATCH endpoint, and auto-allowed SSO domains - Document new PATCH /auth/connections/{id} endpoint for updating connections - Add sign_in_options and sign_in_option_id for account/org pickers - Add sso_provider as CUA-preferred alternative to sso_button_selector - Update SSO docs to reflect auto-allowed provider domains - Fix health check intervals (Start-Up is 20 min, not 15 min) - Add FAQ entry for trial org access to managed auth --- auth/credentials.mdx | 6 ++-- auth/faq.mdx | 10 +++++-- auth/hosted-ui.mdx | 33 +++++++++++++++++++-- auth/overview.mdx | 2 +- auth/programmatic.mdx | 68 ++++++++++++++++++++++++++++++++++++++++--- 5 files changed, 104 insertions(+), 15 deletions(-) diff --git a/auth/credentials.mdx b/auth/credentials.mdx index fff963f..5850aa9 100644 --- a/auth/credentials.mdx +++ b/auth/credentials.mdx @@ -136,9 +136,9 @@ credential = await kernel.credentials.create( ### SSO / OAuth -For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` and include the OAuth provider's domains in `allowed_domains`. +For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` and Kernel automatically clicks the matching SSO button and completes OAuth. -The workflow automatically clicks the matching SSO button and completes OAuth: +Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are automatically allowed — you don't need to add them to `allowed_domains`: ```typescript TypeScript @@ -156,7 +156,6 @@ const auth = await kernel.auth.connections.create({ domain: 'target-site.com', profile_name: 'my-profile', credential: { name: credential.name }, - allowed_domains: ['accounts.google.com', 'google.com'], }); ``` @@ -175,7 +174,6 @@ auth = await kernel.auth.connections.create( domain="target-site.com", profile_name="my-profile", credential={"name": credential.name}, - allowed_domains=["accounts.google.com", "google.com"], ) ``` diff --git a/auth/faq.mdx b/auth/faq.mdx index 86a8a66..d802cc4 100644 --- a/auth/faq.mdx +++ b/auth/faq.mdx @@ -13,10 +13,10 @@ Automatic re-authentication only works when the stored credentials are complete ## How often are health checks performed? -Health checks on regular cadences based on your plan: +Health checks run on regular cadences based on your plan: - Hobbyist (1 hr) -- Start-Up (15 min) -- Enterprise (configurable) +- Start-Up (20 min) +- Enterprise (configurable, down to 5 min) ## How do I know if a Kernel can automatically re-authenticate a connection? @@ -55,6 +55,10 @@ If a login attempt fails, Kernel will retry with exponential backoff. After mult Managed Auth works with most websites. Sites with aggressive bot detection may require additional configuration (stealth mode, proxies). Passkeys and hardware security keys are not currently supported. +## Is Managed Auth available during a trial? + +Yes. Managed Auth and browser profiles are available during your trial period with the same capabilities as the plan you're trialing. + ## How is Managed Auth billed? Managed Auth is included on all paid plans with no per-connection fees. It uses browser sessions to log in and keep your sessions fresh—these count toward your browser usage like any other browser session. diff --git a/auth/hosted-ui.mdx b/auth/hosted-ui.mdx index 9956dae..3336437 100644 --- a/auth/hosted-ui.mdx +++ b/auth/hosted-ui.mdx @@ -240,14 +240,16 @@ auth = await kernel.auth.connections.create( Sites with "Sign in with Google/GitHub/Microsoft" are supported. The user completes the OAuth flow with the provider, and the authenticated session is automatically saved to the Kernel profile. -Make sure to add all of the OAuth provider's domains to `allowed_domains`: +Common SSO provider domains are automatically allowed by default, including Google, Microsoft/Azure AD, Okta, Auth0, Apple, GitHub, Facebook, LinkedIn, Amazon Cognito, OneLogin, and Ping Identity. You don't need to add these to `allowed_domains`. + +For custom or less common OAuth providers, add their domains to `allowed_domains`: ```typescript TypeScript const auth = await kernel.auth.connections.create({ domain: 'example.com', profile_name: 'my-profile', - allowed_domains: ['accounts.google.com', 'google.com'], + allowed_domains: ['sso.custom-provider.com'], }); ``` @@ -255,11 +257,36 @@ const auth = await kernel.auth.connections.create({ auth = await kernel.auth.connections.create( domain="example.com", profile_name="my-profile", - allowed_domains=["accounts.google.com", "google.com"], + allowed_domains=["sso.custom-provider.com"], +) +``` + + +### Updating a Connection + +After creating a connection, you can update its configuration using `auth.connections.update`: + + +```typescript TypeScript +await kernel.auth.connections.update(auth.id, { + login_url: 'https://example.com/new-login', + health_check_interval: 1800, + save_credentials: true, +}); +``` + +```python Python +await kernel.auth.connections.update( + auth.id, + login_url="https://example.com/new-login", + health_check_interval=1800, + save_credentials=True, ) ``` +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. + ### Post-Login URL After successful authentication, `post_login_url` will be set to the page where the login landed. Use this start your automation from the right place: diff --git a/auth/overview.mdx b/auth/overview.mdx index 0f6d94b..f1493cf 100644 --- a/auth/overview.mdx +++ b/auth/overview.mdx @@ -118,7 +118,7 @@ await page.goto("https://netflix.com") The most valuable workflows live behind logins. Managed Auth provides: - **Works on any website** - Login pages are discovered and handled automatically -- **SSO/OAuth support** - "Sign in with Google/GitHub/Microsoft" buttons work out-of-the-box via `allowed_domains` +- **SSO/OAuth support** - "Sign in with Google/GitHub/Microsoft" buttons work out-of-the-box, with common SSO provider domains automatically allowed - **2FA/OTP handling** - TOTP codes automated, SMS/email/push OTP are supported - **Post-login URL** - Get the URL where login landed (`post_login_url`) so you can start automations from the right page - **Session monitoring** - Automatic re-authentication when sessions expire with stored credentials diff --git a/auth/programmatic.mdx b/auth/programmatic.mdx index d3f7696..b9d5f76 100644 --- a/auth/programmatic.mdx +++ b/auth/programmatic.mdx @@ -256,9 +256,33 @@ if state.pending_sso_buttons: -Remember to set `allowed_domains` on the connection to include the OAuth provider's domain (e.g., `accounts.google.com`). +Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are automatically allowed. For custom OAuth providers, add their domains to `allowed_domains` on the connection. +### SSO Provider (CUA) + +As an alternative to `sso_button_selector`, you can submit the SSO provider name directly using `sso_provider`. This is the preferred approach when using CUA (Computer Use Agent) mode: + + +```typescript TypeScript +if (state.pending_sso_buttons?.length) { + // Submit by provider name instead of selector + await kernel.auth.connections.submit(auth.id, { + sso_provider: state.pending_sso_buttons[0].provider // e.g., "google" + }); +} +``` + +```python Python +if state.pending_sso_buttons: + # Submit by provider name instead of selector + await kernel.auth.connections.submit( + auth.id, + sso_provider=state.pending_sso_buttons[0]["provider"], # e.g., "google" + ) +``` + + ### MFA Selection When the site offers multiple MFA methods, they appear in `mfa_options`: @@ -270,7 +294,7 @@ if (state.mfa_options?.length) { for (const opt of state.mfa_options) { console.log(`${opt.type}: ${opt.label}`); } - + // Submit the selected MFA method await kernel.auth.connections.submit(auth.id, { mfa_option_id: 'sms' @@ -283,7 +307,7 @@ if state.mfa_options: # Available types: sms, email, totp, push, call, security_key for opt in state.mfa_options: print(f"{opt['type']}: {opt['label']}") - + # Submit the selected MFA method await kernel.auth.connections.submit( auth.id, @@ -294,6 +318,42 @@ 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. +### 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`: + + +```typescript TypeScript +if (state.sign_in_options?.length) { + // Show available options to the user + for (const opt of state.sign_in_options) { + console.log(`${opt.id}: ${opt.label}`); + if (opt.description) console.log(` ${opt.description}`); + } + + // Submit the selected option + await kernel.auth.connections.submit(auth.id, { + sign_in_option_id: state.sign_in_options[0].id + }); +} +``` + +```python Python +if state.sign_in_options: + # Show available options to the user + for opt in state.sign_in_options: + print(f"{opt['id']}: {opt['label']}") + if opt.get("description"): + print(f" {opt['description']}") + + # Submit the selected option + await kernel.auth.connections.submit( + auth.id, + sign_in_option_id=state.sign_in_options[0]["id"], + ) +``` + + ### External Actions (Push, Security Key) When the site requires an action outside the browser (push notification, security key tap), the step becomes `AWAITING_EXTERNAL_ACTION`: @@ -326,7 +386,7 @@ The `flow_step` field indicates what the flow is waiting for: | Step | Description | |------|-------------| | `DISCOVERING` | Finding the login page and analyzing it | -| `AWAITING_INPUT` | Waiting for field values, SSO button click, or MFA selection | +| `AWAITING_INPUT` | Waiting for field values, SSO button click, SSO provider selection, MFA selection, or sign-in option selection | | `SUBMITTING` | Processing submitted values | | `AWAITING_EXTERNAL_ACTION` | Waiting for push approval, security key, etc. | | `COMPLETED` | Flow has finished | From a8dfb8b5e118db532ff76a97fc918e2dc1135d19 Mon Sep 17 00:00:00 2001 From: masnwilliams <43387599+masnwilliams@users.noreply.github.com> Date: Tue, 24 Mar 2026 02:41:28 +0000 Subject: [PATCH 2/3] Add sign-in options, SSO provider, update connections, and FAQ improvements - Document sign_in_options field with id/label/description and distinguishing note from MFA - Document sso_provider as singular string state field with distinguishing note from SSO buttons - Add Updating Connections section with PATCH fields table and SDK examples - Add sign-in options FAQ linking to programmatic docs - Clarify health check intervals as plan minimums (users can set higher) - Add common error codes (credentials_invalid, bot_detected, captcha_blocked) to failure FAQ Co-Authored-By: Claude Opus 4.6 --- auth/faq.mdx | 16 ++++++++++----- auth/programmatic.mdx | 48 ++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 56 insertions(+), 8 deletions(-) diff --git a/auth/faq.mdx b/auth/faq.mdx index d802cc4..e0b9623 100644 --- a/auth/faq.mdx +++ b/auth/faq.mdx @@ -13,10 +13,10 @@ Automatic re-authentication only works when the stored credentials are complete ## How often are health checks performed? -Health checks run on regular cadences based on your plan: -- Hobbyist (1 hr) -- Start-Up (20 min) -- Enterprise (configurable, down to 5 min) +Health checks run on regular cadences. The default intervals are the minimum for each plan — you can always set a longer (less frequent) interval if you'd like: +- Hobbyist: every 1 hour minimum +- Start-Up: every 20 minutes minimum +- Enterprise: every 5 minutes minimum ## How do I know if a Kernel can automatically re-authenticate a connection? @@ -35,6 +35,10 @@ If your login flow requires one of these, you can still automate around it: - **Switch to TOTP** — If the site supports authenticator apps, add a `totp_secret` to your credential. TOTP codes are generated automatically, so the login flow won't require external action. - **Trigger manual re-auth** — Start a new login session and route the user through the [Hosted UI](/auth/hosted-ui) or [Programmatic](/auth/programmatic) flow. +## What are sign-in options? + +Sign-in options are non-MFA choices that some sites present during login, such as account pickers ("Which account do you want to use?") or organization selectors. Unlike MFA options which are security challenges, sign-in options are informational choices that route the login flow. They appear in the session state as `sign_in_options` and are submitted via `sign_in_option_id`. See the [Programmatic flow guide](/auth/programmatic#sign-in-options-accountorg-pickers) for details and SDK examples. + ## Which authentication methods are supported? Managed Auth supports username/password authentication and most SSO providers. @@ -45,7 +49,9 @@ Passkey-based authentication (e.g., Google accounts with passkeys enabled) is no ## What happens if login fails? -If a login attempt fails, Kernel will retry with exponential backoff. After multiple failures, the [login flow](/auth/hosted-ui) will be marked as failed and you'll receive an error. Common failure reasons include: +If a login attempt fails, Kernel will retry with exponential backoff. After multiple failures, the [login flow](/auth/hosted-ui) will be marked as failed and you'll receive an error with a specific error code. Common codes include `credentials_invalid`, `bot_detected`, and `captcha_blocked`. See the [API reference](/api-reference) for the full list of error codes. + +Common failure reasons include: - Invalid credentials - Bot detection blocking the login page diff --git a/auth/programmatic.mdx b/auth/programmatic.mdx index b9d5f76..47e88fa 100644 --- a/auth/programmatic.mdx +++ b/auth/programmatic.mdx @@ -259,9 +259,9 @@ if state.pending_sso_buttons: Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are automatically allowed. For custom OAuth providers, add their domains to `allowed_domains` on the connection. -### SSO Provider (CUA) +### SSO Provider Selection -As an alternative to `sso_button_selector`, you can submit the SSO provider name directly using `sso_provider`. This is the preferred approach when using CUA (Computer Use Agent) mode: +As an alternative to clicking an SSO button by selector, you can submit the SSO provider name directly. When SSO buttons are detected, the session state includes a `sso_provider` field (a string) identifying the provider that Kernel recommends. You can also specify a provider explicitly using the `sso_provider` submit parameter: ```typescript TypeScript @@ -283,6 +283,10 @@ if state.pending_sso_buttons: ``` + +`sso_provider` is a singular string value, not an array. Use `sso_button_selector` when you need to click a specific button by its CSS selector, and `sso_provider` when you want to identify the provider by name (e.g., `"google"`, `"microsoft"`, `"okta"`). + + ### MFA Selection When the site offers multiple MFA methods, they appear in `mfa_options`: @@ -320,7 +324,7 @@ After selecting an MFA method, the flow continues. Poll for `discovered_fields` ### 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`: +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`: ```typescript TypeScript @@ -354,6 +358,10 @@ if state.sign_in_options: ``` + +Sign-in options are distinct from MFA options. MFA options (`mfa_options`) represent second-factor authentication methods like SMS or TOTP. Sign-in options represent non-security choices like "Which account do you want to use?" or "Select your organization." + + ### External Actions (Push, Security Key) When the site requires an action outside the browser (push notification, security key tap), the step becomes `AWAITING_EXTERNAL_ACTION`: @@ -410,6 +418,40 @@ The `status` field indicates the overall connection state: | `AUTHENTICATED` | Profile is logged in and ready to use | | `NEEDS_AUTH` | Profile needs authentication | +## Updating Connections + +After creating a connection, you can update its configuration with `PATCH /auth/connections/{id}`: + +| Field | Description | +|-------|-------------| +| `login_url` | Override the login page URL | +| `credential` | Update the linked credential | +| `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 | +| `proxy` | Proxy configuration for login sessions | + +Only the fields you include are updated—everything else stays the same. + + +```typescript TypeScript +await kernel.auth.connections.update(auth.id, { + login_url: 'https://example.com/login', + health_check_interval: 1800, + save_credentials: true, +}); +``` + +```python Python +await kernel.auth.connections.update( + auth.id, + login_url="https://example.com/login", + health_check_interval=1800, + save_credentials=True, +) +``` + + ## Real-Time Updates with SSE For real-time UIs, you can stream login flow events via Server-Sent Events instead of polling: From 576bab1121f531769502a796fe703bc9611b2474 Mon Sep 17 00:00:00 2001 From: masnwilliams <43387599+masnwilliams@users.noreply.github.com> Date: Tue, 24 Mar 2026 02:44:23 +0000 Subject: [PATCH 3/3] Add scope clarification, force re-auth FAQ, and UX tips - Add scope positioning in overview.mdx: Managed Auth automates login flows - Add tips after complete example in programmatic.mdx: SSO/MFA/account picker pointer and hosted_url fallback - Add passkey error code (unsupported_auth_method) to warning in faq.mdx - Add force re-auth FAQ with .login() code snippet - Add scope FAQ: what types of flows Managed Auth supports Co-Authored-By: Claude Opus 4.6 --- auth/faq.mdx | 31 ++++++++++++++++++++++++++++++- auth/overview.mdx | 2 ++ auth/programmatic.mdx | 8 ++++++++ 3 files changed, 40 insertions(+), 1 deletion(-) diff --git a/auth/faq.mdx b/auth/faq.mdx index e0b9623..2e0d707 100644 --- a/auth/faq.mdx +++ b/auth/faq.mdx @@ -44,7 +44,7 @@ Sign-in options are non-MFA choices that some sites present during login, such a Managed Auth supports username/password authentication and most SSO providers. -Passkey-based authentication (e.g., Google accounts with passkeys enabled) is not currently supported. If a user's SSO provider requires a passkey, the login will fail. +Passkey-based authentication (e.g., Google accounts with passkeys enabled) is not currently supported. If a user's SSO provider requires a passkey, the login will fail with the `unsupported_auth_method` error code. ## What happens if login fails? @@ -65,6 +65,35 @@ Managed Auth works with most websites. Sites with aggressive bot detection may r Yes. Managed Auth and browser profiles are available during your trial period with the same capabilities as the plan you're trialing. +## How do I re-authenticate a connection before the next health check? + +Call `.login()` on any connection at any time to trigger authentication immediately. If the profile is already logged in, it returns quickly without starting a new flow. If the connection needs auth, it starts a new login session. + +This is useful when your workflow needs to ensure a connection is authenticated right now, without waiting for the next scheduled health check. + + +```typescript TypeScript +const state = await kernel.auth.connections.retrieve(auth.id); + +if (state.status === 'NEEDS_AUTH') { + const login = await kernel.auth.connections.login(auth.id); + // Handle login flow as usual +} +``` + +```python Python +state = await kernel.auth.connections.retrieve(auth.id) + +if state.status == "NEEDS_AUTH": + login = await kernel.auth.connections.login(auth.id) + # Handle login flow as usual +``` + + +## What types of flows does Managed Auth support? + +Managed Auth is designed for login and authentication flows — entering credentials, handling SSO redirects, completing MFA challenges, and maintaining sessions. For other browser interactions like form filling, sign-ups, or multi-step workflows, use [Kernel's browser automation](/browsers/overview) directly. + ## How is Managed Auth billed? Managed Auth is included on all paid plans with no per-connection fees. It uses browser sessions to log in and keep your sessions fresh—these count toward your browser usage like any other browser session. diff --git a/auth/overview.mdx b/auth/overview.mdx index f1493cf..dc5b3a9 100644 --- a/auth/overview.mdx +++ b/auth/overview.mdx @@ -115,6 +115,8 @@ await page.goto("https://netflix.com") ## Why Managed Auth? +Managed Auth automates **login flows** — navigating login pages, filling credentials, handling SSO redirects, and completing MFA challenges. It keeps your profiles logged in across sessions. + The most valuable workflows live behind logins. Managed Auth provides: - **Works on any website** - Login pages are discovered and handled automatically diff --git a/auth/programmatic.mdx b/auth/programmatic.mdx index 47e88fa..de1189f 100644 --- a/auth/programmatic.mdx +++ b/auth/programmatic.mdx @@ -218,6 +218,14 @@ if state.status == "AUTHENTICATED": ``` + +This example covers username/password login with 2FA — the most common flow. If the site uses SSO, MFA selection, account pickers, or external actions (push notifications), see [Handling Different Input Types](#handling-different-input-types) below for how to handle each case. + + + +Every programmatic login session also has a `hosted_url`. If your flow encounters an unexpected state, you can redirect the user to this URL to complete login via the [Hosted UI](/auth/hosted-ui) instead. + + ## Handling Different Input Types The basic polling loop handles `discovered_fields`, but login pages can require other input types too.