diff --git a/auth/configuration.mdx b/auth/configuration.mdx index 2a8e61e..b2e8284 100644 --- a/auth/configuration.mdx +++ b/auth/configuration.mdx @@ -4,13 +4,13 @@ sidebarTitle: "Configuration" description: "Shared options for managed auth connections, regardless of integration flow" --- -Managed Auth Connections are configured the same way regardless of how you collect credentials — via [Hosted UI](/auth/hosted-ui), the [React component](/auth/react), or the [programmatic flow](/auth/programmatic). The options below live on the connection itself and apply to the initial login, every background health check, and every automatic re-authentication. +Managed Auth connections use the same configuration whether you collect credentials through the [Hosted UI](/auth/hosted-ui), the [React component](/auth/react), or the [programmatic flow](/auth/programmatic). These options apply to the initial login, every background health check, and each automatic reauthentication attempt. ## Credentials and Auto-Reauth -Credentials are saved after every successful login, enabling automatic re-authentication when the session expires. One-time codes (TOTP, SMS, etc.) are not saved. +By default, Kernel saves durable credential fields after a successful login. Kernel can automatically reauthenticate credential-only flows and attempts to provide TOTP codes when needed. Submitted one-time codes (TOTP, SMS, etc.) aren't saved. -To opt out of credential saving, set `save_credentials: false` when creating the connection. See [Credentials](/auth/credentials) for more on automated authentication. +To opt out of credential saving, set `save_credentials: false` when creating the connection. See [Credentials](/auth/credentials) for configuration examples. Automatic re-authentication is gated by two boolean flags that both default to `true`: @@ -56,7 +56,9 @@ _ = auth Both flags can be flipped on an existing connection with `auth.connections.update`; changes take effect immediately on the running connection. -Setting `auto_reauth: true` is an opt-in only — it doesn't guarantee reauth is feasible. The system still needs what it requires to perform the login (e.g. saved credentials for the required fields). If those preconditions aren't met when a health check fails, the connection transitions to `NEEDS_AUTH` even with `auto_reauth: true`. +Automatic reauthentication requires a previously successful login and saved credentials for the durable login fields. Setting `auto_reauth: true` permits Kernel to attempt it but doesn't guarantee the next login will succeed. + +If Kernel can't complete an automatic attempt, the connection transitions to `NEEDS_AUTH` so you can start a new login. ## Custom Login URL @@ -96,7 +98,7 @@ _ = auth ## SSO/OAuth Support -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. +Managed Auth supports common "Sign in with Google/GitHub/Microsoft" flows. The user completes the OAuth flow with the provider, and Kernel saves the authenticated session to the profile. Automatic reauthentication depends on the provider's login requirements. See [Can this connection auto-reauth?](/auth/connection-lifecycle#can-this-connection-auto-reauth) for how Kernel determines eligibility. 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`. diff --git a/auth/connection-lifecycle.mdx b/auth/connection-lifecycle.mdx index 2260451..b26af6e 100644 --- a/auth/connection-lifecycle.mdx +++ b/auth/connection-lifecycle.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Lifecycle" description: "How connections stay authenticated, and what to do when one breaks" --- -Once a Managed Auth connection is `AUTHENTICATED`, Kernel runs periodic health checks and automatic re-authentication to keep the session valid. This page covers the runtime lifecycle of a connection: how the check-and-reauth loop works, how to tune it, what blocks auto-reauth, and how to debug a connection that won't stay logged in. +Once a Managed Auth connection is `AUTHENTICATED`, Kernel runs periodic health checks. For eligible flows, Kernel can automatically reauthenticate the session to keep it valid. This page covers the runtime lifecycle, configuration options, and recovery steps. ## The lifecycle @@ -17,12 +17,12 @@ After the initial login, every connection moves through this loop: A check needs concrete evidence to conclude. If the site returns a challenge page, times out, partially loads, or shows something ambiguous, the result is inconclusive and the connection is left exactly as it was. Nothing happens until the next check. - If the check finds the session **definitely** expired and the connection's `can_reauth` is `true`, Kernel runs the saved login flow with the stored credentials in the background. A successful login resets the loop. + If the check finds the session **definitely** expired and the connection's `can_reauth` is `true`, Kernel runs the saved credential-based login flow in the background. A successful login resets the loop. An inconclusive check never triggers reauth. Kernel would rather check again on the next cycle than log in again unnecessarily — a spurious login can trip risk checks on the site, prompt a device-verification email, or invalidate a working session. - - If auto-reauth isn't possible — credentials aren't linked, the saved flow requires human input, or the login keeps failing — the connection's `status` flips to `NEEDS_AUTH` and a new login session is required. + + If automatic reauthentication isn't possible — for example, credentials are missing, human input is required, or the login keeps failing — the connection's `status` changes to `NEEDS_AUTH`. Start a new login session to continue. @@ -66,24 +66,27 @@ if err != nil { ### Sessions that expire faster than the interval -Kernel keeps re-authenticating even when every health check finds the session expired. A successful login resets the auto-reauth state, so a site whose session TTL is shorter than your health check interval is re-authenticated on every cycle rather than being given up on. +For an eligible connection, Kernel continues reauthenticating when every health check finds the session expired. A successful login resets the automatic reauthentication state, so a site whose session TTL is shorter than your health check interval is reauthenticated on every cycle. If you're seeing the connection flip to `NEEDS_AUTH` frequently and want shorter detection windows, lower `health_check_interval` toward your plan's minimum. ## Can this connection auto-reauth? -Check the `can_reauth` boolean on a connection. It's `true` only when **both** of these hold: +Check the `can_reauth` boolean on a connection. It describes eligibility to attempt reauthentication, not whether the next login will succeed. It's `true` only when all of these conditions hold: -1. **A credential is linked** — stored in Kernel or sourced via [1Password](/integrations/1password). -2. **No known human-only requirement is recorded** — for example, an sms/email code, push approval, or other external action. +1. **A previous login succeeded** — Kernel has recorded the result of a completed login. +2. **A credential is linked** — It's stored in Kernel or sourced from [1Password](/integrations/1password). +3. **No blocking requirement is recorded** — Kernel hasn't recorded a requirement that prevents an automatic attempt. -If either fails, the connection will move to `NEEDS_AUTH` on the next expired session and wait for a fresh login. A site can still present a new or conditional challenge during reauth; if Kernel can't resolve it safely, reauth stops and the connection moves to `NEEDS_AUTH`. +Use `can_reauth_reason` to see why the connection is or isn't eligible. See [Get auth connection](https://kernel.sh/docs/api-reference/managed-auth/get-auth-connection) for the possible values. -### External actions that block auto-reauth +`can_reauth` reflects what Kernel knows about the previous login. A site can introduce a new requirement during a later attempt. If Kernel needs input, a choice, or approval, the connection moves to `NEEDS_AUTH` so you can start a new login. -After a successful login, Kernel saves the login flow. If that flow includes steps that require human action, the connection can't auto-reauth because those steps can't be replayed without user input. +### Flows that need input, a choice, or approval -If your flow requires one of these, you can still automate around it: +After a successful login, Kernel saves the login flow. If a later attempt needs input, a choice, or approval, the connection moves to `NEEDS_AUTH` instead of guessing how to proceed. + +You can handle these flows in two ways: - **Switch to TOTP** — If the site supports authenticator apps, add a `totp_secret` to your credential. Codes are generated on demand, so the flow no longer needs external action. If a code expires before the site accepts it, Kernel retries with a fresh one. - **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. diff --git a/auth/credentials.mdx b/auth/credentials.mdx index afd46f4..518db9e 100644 --- a/auth/credentials.mdx +++ b/auth/credentials.mdx @@ -1,13 +1,13 @@ --- title: "Credentials" -description: "Automate authentication with stored credentials" +description: "Use stored credentials for login and automatic reauthentication" --- -Credentials allow you to store login information securely and enable Kernel's automated re-authentication without requiring user interaction. +Credentials let you store login information securely. Kernel can automatically authenticate credential-only flows and attempts to provide TOTP codes when needed. **There are three ways to provide credentials:** - **Automatically save during login** — Capture credentials directly from the user when they log in via [Hosted UI](/auth/hosted-ui) or [Programmatic](/auth/programmatic) -- **Pre-store in Kernel** — Create credentials before any login for fully headless automation +- **Pre-store in Kernel** — Create credentials before login for supported headless authentication flows - **Connect 1Password** — Use credentials from your existing 1Password vaults @@ -16,7 +16,7 @@ Credentials allow you to store login information securely and enable Kernel's au ## Save credentials during login -By default, credentials entered during login are automatically saved for re-authentication. No extra parameters are needed: +By default, Kernel saves durable credential fields entered during login so they can be used for eligible reauthentication attempts. No extra parameters are needed: ```typescript TypeScript @@ -36,7 +36,7 @@ _ = login ``` -Once saved, browser profiles stay authenticated automatically. When the session expires, Kernel re-authenticates using the stored credentials. Credentials are updated after every successful login. One-time codes (TOTP, SMS, etc.) are not saved. +Once saved, the browser profile reuses its authenticated session until the site expires it. For supported credential-based flows, Kernel can then reauthenticate with the stored values. Credentials are updated after every successful login. Submitted one-time codes aren't saved; Kernel generates TOTP codes from a stored `totp_secret`. To opt out of credential saving, set `save_credentials: false` when creating the connection: @@ -74,7 +74,7 @@ _ = auth ## Pre-store credentials -For fully automated flows where no user is involved, create credentials upfront: +For credential-based flows that you want to run without user input, create credentials upfront: ```typescript TypeScript @@ -127,7 +127,7 @@ const auth = await kernel.auth.connections.create({ credential: { name: credential.name }, }); -// Start login - authenticates automatically using stored credentials +// Start login with stored credentials const login = await kernel.auth.connections.login(auth.id); ``` @@ -138,7 +138,7 @@ auth = await kernel.auth.connections.create( credential={"name": credential.name}, ) -# Start login - authenticates automatically using stored credentials +# Start login with stored credentials login = await kernel.auth.connections.login(auth.id) ``` @@ -156,7 +156,7 @@ if err != nil { panic(err) } -// Start login - authenticates automatically using stored credentials +// Start login with stored credentials login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{}) if err != nil { panic(err) @@ -167,7 +167,7 @@ _ = login ### 2FA with TOTP -For sites with authenticator app 2FA, include `totp_secret` to fully automate login: +For sites with authenticator app 2FA, include `totp_secret` so Kernel can generate a fresh code during automatic login and reauthentication: ```typescript TypeScript @@ -215,9 +215,9 @@ _ = credential ### SSO / OAuth -For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` and Kernel automatically clicks the matching SSO button and completes OAuth. +For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` so Kernel can select the matching SSO route. Automatic completion depends on the provider's login requirements. -Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are automatically allowed — you don't need to add them to `allowed_domains`: +Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are allowed by default, so you don't need to add them to `allowed_domains`: ```typescript TypeScript diff --git a/auth/faq.mdx b/auth/faq.mdx index 7f62f71..ba526f1 100644 --- a/auth/faq.mdx +++ b/auth/faq.mdx @@ -4,7 +4,7 @@ title: FAQ ## How does automatic re-authentication work? -When you link credentials to a connection, Kernel runs periodic health checks, detects logged-out sessions, and re-authenticates in the background so the profile stays logged in. See [Connection Lifecycle](/auth/connection-lifecycle) for the full lifecycle, cadence options, and `can_reauth` rules. +When you link credentials to a connection, Kernel runs periodic health checks and can reauthenticate supported credential-based flows in the background. This includes TOTP when Kernel can provide the authenticator code. See [Connection Lifecycle](/auth/connection-lifecycle) for the full lifecycle, cadence options, and `can_reauth` rules. ## What are auth choices? @@ -12,10 +12,10 @@ Auth choices are visible routes a site presents during login, including mfa meth ## Which authentication methods are supported? -Managed Auth supports username/password authentication and most SSO providers. +Managed Auth supports common credential, SSO, and multi-step login flows. Automatic reauthentication uses stored credentials and attempts to provide TOTP codes when needed. -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. +Passkey-only authentication isn't currently supported. If a site's SSO provider requires a passkey, the login returns `unsupported_auth_method`. Switch the account to a supported sign-in method, such as password and TOTP, then start a new login. ## What happens if login fails? @@ -24,7 +24,7 @@ Kernel surfaces an error code (`credentials_invalid`, `account_locked`, `bot_det ## Can I use Managed Auth with any website? -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. +Managed Auth covers common login flows across a broad range of websites. Site-specific authentication and bot detection can require additional configuration. See [what Managed Auth supports](/auth/overview#why-managed-auth) and test your target flow. ## Is Managed Auth available during a trial? @@ -36,7 +36,7 @@ Call `.login()` on the connection to trigger auth immediately. See [Triggering r ## What types of flows does Managed Auth support? -Managed Auth handles login and authentication flows end-to-end: entering credentials, multi-step login forms (e.g. email on one page, password on the next), SSO redirects, MFA challenges, and keeping sessions alive. For post-login browser work like form filling, sign-ups, or other workflows, use [Kernel's browser automation](/introduction/control) directly. +Managed Auth navigates login pages, enters stored credentials, follows SSO redirects, guides users through additional authentication steps, and saves the resulting browser session. For post-login work like form filling, sign-ups, or other workflows, use [Kernel's browser automation](/introduction/control) directly. ## How do I debug a managed auth session? @@ -44,17 +44,17 @@ Use the **Browser Sessions** tab in the dashboard for live view, or set `record_ ## 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. +Yes. A profile can have any number of auth connections, each for a different domain. When you create a browser with that profile, it loads the saved authentication state for every connected domain. This is useful for two common patterns: -- **Multi-site workflows** — Your agent visits multiple sites in a single run (e.g., reads email in Gmail, posts a summary in Slack, and updates a CRM). Attach one auth connection per site to a single profile, and the browser starts logged in to all of them. +- **Multi-site workflows** — Your agent visits multiple sites in a single run (e.g., reads email in Gmail, posts a summary in Slack, and updates a CRM). Attach one auth connection per site to a single profile, and each browser loads the saved authentication state for all of them. - **User-to-profile mapping** — Each end user on your platform gets one profile. All of that user's accounts (Gmail, LinkedIn, GitHub, etc.) are auth connections on their profile. When the user triggers a workflow, launch a browser with their profile. See [Profiles — Multiple auth connections per profile](/auth/profiles#multiple-auth-connections-per-profile) for code examples. ## How is Managed Auth billed? -Managed Auth is included on all 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. +Managed Auth is included on all plans with no per-connection fees. It uses browser sessions for login, health checks, and eligible reauthentication attempts. These count toward your browser usage like any other browser session. -Auth sessions are fast (typically 5-30 seconds each). Kernel monitors session health and re-authenticates automatically when sessions expire—most stay valid for days. For example, keeping 100 auth connections logged in typically costs less than $5/month in browser usage. See [Pricing & Limits](/info/pricing#managed-auth) for details. +Auth sessions are fast (typically 5-30 seconds each). Kernel monitors session health and can automatically reauthenticate eligible credential-based flows when sessions expire. Most sessions stay valid for days. For example, monitoring 100 auth connections typically costs less than $5/month in browser usage. See [Pricing & Limits](/info/pricing#managed-auth) for details. diff --git a/auth/hosted-ui.mdx b/auth/hosted-ui.mdx index 35f9878..6abe611 100644 --- a/auth/hosted-ui.mdx +++ b/auth/hosted-ui.mdx @@ -8,13 +8,13 @@ Collect credentials securely via Kernel's hosted page, then use the authenticate Use the Hosted UI when: - You need users to provide their credentials - You want the simplest integration with minimal code -- You want Kernel to handle 2FA and multi-step login flows +- You want Kernel to guide users through 2FA and multi-step login flows ## Getting started ### 1. Create a Connection -A Managed Auth Connection attaches an authenticated domain to a [profile](/auth/profiles) so you can use the auth connection in future browsers. You can attach multiple auth connections to the same profile — one per domain — to keep several sites authenticated at once. +A Managed Auth connection saves a domain's authentication state to a [profile](/auth/profiles) so future browsers can reuse it. You can attach multiple auth connections to the same profile, one per domain. ```typescript TypeScript @@ -90,7 +90,11 @@ fmt.Println("Redirect to:", login.HostedURL) The user will: 1. See the login page for the target website 2. Enter their credentials -3. Complete 2FA if needed +3. Complete 2FA or another verification step if needed + + +Kernel can automatically reauthenticate credential-only flows and attempts to provide TOTP codes when needed. + ### 4. Stream until completion @@ -150,7 +154,7 @@ The SSE stream closes automatically when the flow succeeds, fails, expires, or i ### 5. Use the Profile -Create browsers with the profile and navigate to the site. The browser session will already be authenticated: +Create browsers with the profile and navigate to the site. The browser loads the authentication state saved during login: ```typescript TypeScript @@ -159,7 +163,7 @@ const browser = await kernel.browsers.create({ stealth: true, }); -// Navigate to the site—you're already logged in +// Navigate with the saved authentication state await page.goto('https://linkedin.com'); ``` @@ -169,7 +173,7 @@ browser = await kernel.browsers.create( stealth=True, ) -# Navigate to the site—you're already logged in +# Navigate with the saved authentication state await page.goto("https://linkedin.com") ``` @@ -184,7 +188,7 @@ if err != nil { panic(err) } -// Navigate to the site—you're already logged in +// Navigate with the saved authentication state _, err = client.Browsers.Playwright.Execute(ctx, browser.SessionID, kernel.BrowserPlaywrightExecuteParams{ Code: `await page.goto("https://linkedin.com");`, }) @@ -234,7 +238,7 @@ if (finalState?.flow_status === 'SUCCESS') { stealth: true, }); - // Navigate to the site—you're already logged in + // Navigate with the saved authentication state await page.goto('https://doordash.com'); } ``` @@ -269,7 +273,7 @@ if final_state and final_state.flow_status == "SUCCESS": stealth=True, ) - # Navigate to the site—you're already logged in + # Navigate with the saved authentication state await page.goto("https://doordash.com") ``` @@ -332,7 +336,7 @@ func main() { panic(err) } - // Navigate to the site—you're already logged in + // Navigate with the saved authentication state _, err = client.Browsers.Playwright.Execute(ctx, browser.SessionID, kernel.BrowserPlaywrightExecuteParams{ Code: `await page.goto("https://doordash.com");`, }) diff --git a/auth/overview.mdx b/auth/overview.mdx index 59003d2..52f5e91 100644 --- a/auth/overview.mdx +++ b/auth/overview.mdx @@ -3,13 +3,13 @@ title: "Overview" description: "Maintain authenticated browser sessions for agents" --- -Managed Auth creates and maintains authenticated browser sessions for your AI agents. Store credentials once, and Kernel re-authenticates automatically when needed. When you launch Kernel browsers with Managed Auth connections, your agent starts already logged in and ready to go. +Managed Auth creates and maintains authenticated browser sessions for your AI agents. Store credentials once, and Kernel can automatically reauthenticate supported login flows when needed. When you launch Kernel browsers with Managed Auth connections, your agent can start logged in and ready to go. ## How It Works - A **Managed Auth Connection** attaches an authenticated domain to a browser [profile](/auth/profiles) so you can automatically be logged in when you launch future browsers. A single profile can have multiple auth connections — one per domain you want to keep authenticated. + A **Managed Auth Connection** attaches a domain's authentication state to a browser [profile](/auth/profiles) so future browsers can reuse it. A single profile can have multiple auth connections, one per domain. ```typescript TypeScript @@ -43,7 +43,7 @@ _ = auth A **Managed Auth Session** is the corresponding login flow for the specified connection. Users provide credentials via a Kernel-hosted page or your own UI. - Specify a [Credential](/auth/credentials) to enable re-authentication without user input. + Specify a [Credential](/auth/credentials) to enable automatic reauthentication for supported credential-based flows. ```typescript TypeScript @@ -116,7 +116,7 @@ if authenticated { - Once the auth connection completes, the authenticated session is saved to the browser [profile](/auth/profiles) specified in step 1. You can attach additional auth connections to the same profile for other domains. When you create a browser with the profile, all of its auth connections are available — the browser session will already be logged in to every connected domain. + Once the auth connection completes, the authenticated session is saved to the browser [profile](/auth/profiles) specified in step 1. You can attach additional auth connections to the same profile for other domains. When you create a browser with the profile, it loads the saved authentication state for every connected domain. ```typescript TypeScript @@ -125,7 +125,7 @@ const browser = await kernel.browsers.create({ stealth: true, }); -// Navigate to the site—you're already logged in +// Navigate with the saved authentication state await page.goto('https://netflix.com'); ``` @@ -135,7 +135,7 @@ browser = await kernel.browsers.create( stealth=True, ) -# Navigate to the site—you're already logged in +# Navigate with the saved authentication state await page.goto("https://netflix.com") ``` @@ -151,7 +151,7 @@ if err != nil { } _ = browser -// Navigate to the site—you're already logged in +// Navigate with the saved authentication state _, err = client.Browsers.Playwright.Execute(ctx, browser.SessionID, kernel.BrowserPlaywrightExecuteParams{ Code: `await page.goto("https://netflix.com");`, }) @@ -164,7 +164,7 @@ if err != nil { -The steps above are the integration loop — what you wire up once per connection. After the initial login, the connection enters its runtime loop of periodic health checks and automatic re-authentication; see [Connection Lifecycle](/auth/connection-lifecycle) for how that works and how to tune it. +The steps above are the integration loop you wire up once per connection. After the initial login, Kernel monitors the connection with periodic health checks and can automatically reauthenticate eligible flows. See [Connection Lifecycle](/auth/connection-lifecycle) for the runtime behavior and configuration options. ## Choose Your Integration @@ -172,7 +172,7 @@ The steps above are the integration loop — what you wire up once per connectio **Start here** - Simplest integration - Redirect users to Kernel's hosted page. Add features incrementally: save credentials for auto-reauth, custom login URLs, SSO support. + Redirect users to Kernel's hosted page. Add features incrementally: save credentials for eligible automatic reauthentication, set custom login URLs, and configure SSO. **Embed in your app** - Drop-in component @@ -189,16 +189,16 @@ The steps above are the integration loop — what you wire up once per connectio ## 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. +Managed Auth runs **login flows** by navigating login pages, filling credentials, following SSO redirects, and guiding users through additional authentication steps. It saves the resulting session state to a reusable profile. 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, with common SSO provider domains automatically allowed -- **2FA/OTP handling** - TOTP codes automated with automatic retry on expiry, SMS/email/push OTP are supported +- **Broad site coverage** - Login pages are discovered and handled across common website login flows +- **SSO/OAuth support** - Kernel follows common SSO redirects. Common provider domains are allowed by default; add custom provider domains to `allowed_domains` +- **2FA/OTP handling** - Kernel attempts to provide TOTP codes automatically; interactive login can collect other verification steps - **Post-login URL** - Get the URL where login landed (`post_login_url`) so you can start automations from the right page -- **Session monitoring** - [Periodic health checks](/auth/connection-lifecycle) and automatic re-authentication when sessions expire with stored credentials -- **Secure by default** - Credentials encrypted at rest, never exposed in API responses, or passed to LLMs +- **Session monitoring** - [Periodic health checks](/auth/connection-lifecycle) and automatic reauthentication for eligible credential-based flows +- **Secure by default** - Credentials are encrypted at rest and never exposed in API responses or passed to LLMs ## Security diff --git a/auth/profiles.mdx b/auth/profiles.mdx index cc59d14..cb4d6ef 100644 --- a/auth/profiles.mdx +++ b/auth/profiles.mdx @@ -7,7 +7,7 @@ Profiles let you capture browser state created during a session (cookies and loc ## 1. Create a profile -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. +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 loads the saved authentication state for each connection. 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). @@ -355,11 +355,11 @@ The API and SDKs support listing, deleting, and downloading profile data as JSON ## Multiple auth connections per profile -A profile can have any number of auth connections, each for a different domain. When you launch a browser with that profile, it is already logged in to every connected domain. +A profile can have any number of auth connections, each for a different domain. When you launch a browser with that profile, it loads the saved authentication state for every connected domain. ### Multi-site workflows -If your agent interacts with multiple sites as part of a single workflow, attach an auth connection for each site to one profile. The browser starts logged in to all of them: +If your agent interacts with multiple sites in one workflow, attach an auth connection for each site to one profile. The browser loads the saved authentication state for all of them: ```typescript TypeScript @@ -381,7 +381,7 @@ const crmAuth = await kernel.auth.connections.create({ // Authenticate each connection (omitted for brevity) -// Launch a single browser — logged in to Gmail, Slack, and the CRM +// Launch a browser with the saved state for all three sites const browser = await kernel.browsers.create({ profile: { name: 'workflow-bot' }, stealth: true, @@ -407,7 +407,7 @@ crm_auth = await kernel.auth.connections.create( # Authenticate each connection (omitted for brevity) -# Launch a single browser — logged in to Gmail, Slack, and the CRM +# Launch a browser with the saved state for all three sites browser = await kernel.browsers.create( profile={"name": "workflow-bot"}, stealth=True, @@ -451,7 +451,7 @@ _ = crmAuth // Authenticate each connection (omitted for brevity) -// Launch a single browser — logged in to Gmail, Slack, and the CRM +// Launch a browser with the saved state for all three sites browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{ Profile: shared.BrowserProfileParam{ Name: kernel.String("workflow-bot"), diff --git a/auth/programmatic.mdx b/auth/programmatic.mdx index b55acf6..cabeee0 100644 --- a/auth/programmatic.mdx +++ b/auth/programmatic.mdx @@ -90,7 +90,7 @@ if err != nil { ``` -A successful interactive login can save submitted credentials for automatic re-authentication. +A successful interactive login can save submitted credentials for automatic reauthentication. During TOTP flows, Kernel attempts to provide the authenticator code automatically. ### 3. Stream and submit diff --git a/browsers/faq.mdx b/browsers/faq.mdx index fd0ac4d..0164bc2 100644 --- a/browsers/faq.mdx +++ b/browsers/faq.mdx @@ -28,7 +28,7 @@ What tends to increase bot-detection friction: - **High-volume or high-concurrency scraping** — many requests from the same exit IP raise the block rate. Spread load across [proxies](/proxies/overview) and reuse [Profiles](/auth/profiles). - **Aggressive detection vendors** (Cloudflare, DataDome, PerimeterX, Imperva, Akamai) — these can challenge even anonymous page loads. Enable [stealth mode](/browsers/bot-detection/stealth) and consider [computer controls](/browsers/computer-controls) for more human-like interaction. -For workflows behind a login, [Managed Auth](/auth/overview) handles the login flow and keeps sessions persistently authenticated across runs. +For workflows behind a login, [Managed Auth](/auth/overview) can keep sessions authenticated across runs for supported login flows. Because behavior is site- and configuration-specific, test your target site manually before automating — see the [bot detection guide](/browsers/bot-detection/overview) for the recommended approach and mitigations. diff --git a/browsers/pools.mdx b/browsers/pools.mdx index 37670f1..e870816 100644 --- a/browsers/pools.mdx +++ b/browsers/pools.mdx @@ -202,7 +202,7 @@ As a best practice, release each browser when you're done with it — that retur ## Profiles with browser pools -A [profile](/auth/profiles) carries login state — cookies and local storage — into a browser; use [Managed Auth](/auth/overview) to populate and maintain it. Put the profile on the browser pool when every browser should share one identity; leave it off and attach it after acquiring when each task needs its own (see [Per-user profiles with browser pools](#per-user-profiles-with-browser-pools)). +A [profile](/auth/profiles) carries login state, including cookies and local storage, into a browser. Use [Managed Auth](/auth/overview) to populate that state and monitor its health. Put the profile on the browser pool when every browser should share one identity; leave it off and attach it after acquiring when each task needs its own (see [Per-user profiles with browser pools](#per-user-profiles-with-browser-pools)). A profile attached to the pool is loaded **read-only**. Every browser in the pool shares it, so `save_changes` doesn't apply and is silently ignored if sent — this prevents concurrent writes from corrupting the profile. diff --git a/info/pricing.mdx b/info/pricing.mdx index 705bd88..1eb483d 100644 --- a/info/pricing.mdx +++ b/info/pricing.mdx @@ -100,7 +100,7 @@ If you need higher rate limits, [contact us](https://calendly.com/d/d3tn-5kp-5yt Note: A browser pool counts toward your concurrency limit whether or not its browsers are currently acquired — a browser pool sized to 40 browsers uses 40 of your limit. Browser pools are available on Start-Up and Enterprise plans. -Managed Auth is included on all plans with no per-connection fees. Under the hood, it uses browser sessions to log in and keep your sessions fresh—these count toward your browser usage and concurrency like any other browser session. +Managed Auth is included on all plans with no per-connection fees. It uses browser sessions for login, health checks, and eligible automatic reauthentication. These count toward your browser usage and concurrency like any other browser session. -Auth sessions are fast (typically 5-30 seconds each). Kernel monitors session health and re-authenticates automatically when sessions expire—most stay valid for days. For example, keeping 100 auth connections logged in typically costs less than $5/month in browser usage. +Auth sessions are fast, typically 5-30 seconds each, and most website sessions remain valid for days. For example, monitoring 100 auth connections typically costs less than $5/month in browser usage. \ No newline at end of file diff --git a/integrations/1password.mdx b/integrations/1password.mdx index 985ac5e..54e67b2 100644 --- a/integrations/1password.mdx +++ b/integrations/1password.mdx @@ -4,7 +4,7 @@ description: "Use credentials from your 1Password vaults for Managed Auth" icon: "/images/integration-icons/1password-logo-transparent.svg" --- -Connect 1Password to automatically use credentials from your existing vaults with [Managed Auth](/auth/overview). No need to manually create credentials in Kernel—1Password items are discovered by domain matching. +Connect 1Password to use credentials from your existing vaults with [Managed Auth](/auth/overview). You don't need to recreate credentials in Kernel because 1Password items are discovered by domain matching. ## How It Works @@ -138,11 +138,11 @@ If multiple items match a domain, the first match is used. Organize your vaults ## TOTP Support -If your 1Password item has a one-time password (TOTP) field configured, it will be used automatically for 2FA—no additional setup needed. +If your 1Password item has a one-time password (TOTP) field configured, Kernel can generate fresh codes for automatic login and reauthentication. No additional setup is needed. ## Supported Login Types -Managed Auth fills **direct logins** from 1Password items: username/password credentials plus any TOTP field for 2FA. This includes signing directly into an identity provider itself—for example logging into a Google account with its stored username, password, and TOTP. +Managed Auth fills **direct logins** from 1Password items: username and password credentials plus any TOTP field for 2FA. These direct flows support automatic reauthentication, including TOTP when its secret is stored in 1Password. This includes signing directly into an identity provider itself—for example, logging into a Google account with its stored username, password, and TOTP. 1Password's linked-item "sign in with" references are not supported. When an item delegates authentication to a separate item—for example a site item set to **sign in with** another login—that link is not exposed through the 1Password API, so Managed Auth can't follow it to the underlying credential. Store a direct login (username/password, plus a TOTP field if needed) for the target site instead. diff --git a/introduction/create.mdx b/introduction/create.mdx index 8437edf..bc9f8aa 100644 --- a/introduction/create.mdx +++ b/introduction/create.mdx @@ -81,7 +81,7 @@ Most of what you'll tune at creation time falls into four buckets: Required for WebGL, video, and canvas-heavy workloads. Trades off standby support. - Persist cookies, storage, and logged-in sessions across runs with a [profile](/auth/profiles), or hand auth off to Kernel entirely with [managed auth](/auth/overview). + Persist cookies, storage, and authenticated sessions across runs with a [profile](/auth/profiles), or learn how to hand supported login flows off to Kernel with [Managed Auth](/auth/overview). diff --git a/reference/cli/managed-auth.mdx b/reference/cli/managed-auth.mdx index 659550f..966906c 100644 --- a/reference/cli/managed-auth.mdx +++ b/reference/cli/managed-auth.mdx @@ -5,7 +5,7 @@ title: "Managed Auth" Manage [managed auth](/auth/overview) connections, stored credentials, and external credential providers from the CLI. For authenticating the CLI itself (login, logout, API keys), see [Authentication](/reference/cli/auth). ## Connections -A managed auth connection keeps a [profile](/auth/profiles) logged into a domain so future browsers reuse the authenticated session. See [Managed auth](/auth/overview) for concepts and the [programmatic flow](/auth/programmatic) for the SDK equivalent. +A Managed Auth connection saves a domain's authentication state to a [profile](/auth/profiles) so future browsers can reuse it. Eligible credential-based flows can reauthenticate automatically. See [Managed Auth](/auth/overview) for concepts and the [programmatic flow](/auth/programmatic) for the SDK equivalent. ### `kernel auth connections create` Create a managed auth connection for a profile and domain. @@ -17,6 +17,8 @@ Create a managed auth connection for a profile and domain. | `--allowed-domain ` | Additional allowed domains (repeatable). | | `--login-url ` | Login page URL to skip discovery. | | `--health-check-interval ` | Seconds between health checks (300–86400). | +| `--no-health-checks` | Disable periodic health checks. | +| `--no-auto-reauth` | Disable automatic reauthentication attempts after an expired session is detected. | | `--proxy-id ` | Proxy ID to use. | | `--proxy-name ` | Proxy name to use. | | `--credential-provider ` | External credential provider name. | @@ -106,6 +108,8 @@ Update connection settings such as login URL, health checks, credential source, | `--login-url ` | Login page URL (set to an empty string to clear). | | `--allowed-domain ` | Additional allowed domains (replaces the existing list). | | `--health-check-interval ` | Seconds between health checks. | +| `--health-checks` / `--no-health-checks` | Enable or disable periodic health checks. | +| `--auto-reauth` / `--no-auto-reauth` | Enable or disable automatic reauthentication attempts after an expired session is detected. | | `--proxy-id ` | Proxy ID to use. | | `--proxy-name ` | Proxy name to use. | | `--credential-provider ` | External credential provider name. |