From 77562389cdbaec3f693d3dac81898ab2dab5420e Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Tue, 15 Sep 2026 23:06:19 +0000
Subject: [PATCH 01/27] Reframe auth docs around two integration paths
---
auth/credential-fill.mdx | 68 +++++
auth/credentials.mdx | 2 +-
auth/faq.mdx | 2 +-
auth/managed-auth.mdx | 216 +++++++++++++++
auth/overview.mdx | 254 ++++--------------
auth/profiles.mdx | 2 +-
browsers/faq.mdx | 2 +-
browsers/pools.mdx | 4 +-
...use-vault-credentials-in-browser-agent.mdx | 4 +-
changelog.mdx | 34 +--
docs.json | 31 ++-
index.mdx | 4 +-
integrations/1password.mdx | 2 +-
integrations/vercel/eve-extension.mdx | 6 +-
integrations/vercel/foreman.mdx | 2 +-
introduction/create.mdx | 2 +-
proxies/datacenter.mdx | 2 +-
proxies/isp.mdx | 2 +-
proxies/overview.mdx | 2 +-
reference/cli/managed-auth.mdx | 4 +-
vaults/credentials.mdx | 4 +-
vaults/fill.mdx | 2 +-
22 files changed, 400 insertions(+), 251 deletions(-)
create mode 100644 auth/credential-fill.mdx
create mode 100644 auth/managed-auth.mdx
diff --git a/auth/credential-fill.mdx b/auth/credential-fill.mdx
new file mode 100644
index 00000000..cf14b5b5
--- /dev/null
+++ b/auth/credential-fill.mdx
@@ -0,0 +1,68 @@
+---
+title: "Vaults + Credential Fill"
+description: "Collect end-user credentials and inject them into browser forms while controlling the login workflow"
+---
+
+Vaults + Credential Fill gives your application or agent direct control over authentication. Use it when an end user supplies credentials during a task and your workflow needs to own navigation, submission, and recovery.
+
+KERNEL collects credential values or accepts them from a trusted backend, encrypts them in a credential item, and fills selected browser fields without including the values in the fill request or response. Your application or agent decides where to navigate, which fields to fill, when to submit, and how to handle the site's response.
+
+
+ fill writes real values into the browser. Page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them after filling.
+
+
+## When to use it
+
+Vaults + Credential Fill works best when:
+
+- an end user owns the credentials and remains present during the task.
+- a login or authentication prompt can appear in the middle of a workflow.
+- your product needs to control the credential collection experience.
+- your application or agent already handles browser navigation and site-specific recovery.
+- you don't need KERNEL to monitor the session or reauthenticate it automatically.
+
+Choose [Managed Auth](/auth/managed-auth) instead when you want KERNEL to run the login flow, save the authenticated state, monitor the connection, and reauthenticate eligible flows.
+
+## How it works
+
+
+
+ create a vault for each end user or credential-sharing boundary. A vault groups the items that an attached browser session can use.
+
+
+ define a [credential item](/vaults/credentials), then collect values through a KERNEL-hosted form or copy them from a trusted backend. Sensitive values aren't returned by the vault api.
+
+
+ attach the vault when you create the browser. The attachment can't change during the session and grants access to every item in that vault.
+
+
+ navigate to the login page, identify the fields, and invoke [fill](/vaults/fill) with field names and selectors. KERNEL writes the stored values into the selected inputs.
+
+
+ your application or agent submits the form and interprets the result. Fill doesn't submit the form or confirm that authentication succeeded.
+
+
+
+## Credential sources
+
+you can collect values from an end user with KERNEL's hosted collection form or copy them from a credential store that your trusted backend can read. Both paths create the same ready credential item and use the same fill operation.
+
+Today, copying values stores an encrypted KERNEL copy. Credential Fill doesn't accept raw values or a third-party vault reference in the fill request.
+
+## Session state
+
+Credential Fill completes one part of the workflow. It doesn't monitor the resulting session or reauthenticate it later. If you want to reuse the authenticated state, create the browser with a [profile](/auth/profiles) and save its changes after the login succeeds.
+
+## Next steps
+
+
+
+ define fields, collect values, and update credentials without returning sensitive values.
+
+
+ map credential fields to browser inputs and handle completed, failed, or unknown outcomes.
+
+
+ follow the complete collection and browser fill workflow with the sdk or cli.
+
+
diff --git a/auth/credentials.mdx b/auth/credentials.mdx
index 518db9e0..2dae233d 100644
--- a/auth/credentials.mdx
+++ b/auth/credentials.mdx
@@ -1,5 +1,5 @@
---
-title: "Credentials"
+title: "Managed Auth Credentials"
description: "Use stored credentials for login and automatic reauthentication"
---
diff --git a/auth/faq.mdx b/auth/faq.mdx
index ba526f13..ee769780 100644
--- a/auth/faq.mdx
+++ b/auth/faq.mdx
@@ -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 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.
+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/managed-auth#why-managed-auth) and test your target flow.
## Is Managed Auth available during a trial?
diff --git a/auth/managed-auth.mdx b/auth/managed-auth.mdx
new file mode 100644
index 00000000..a7c77aa6
--- /dev/null
+++ b/auth/managed-auth.mdx
@@ -0,0 +1,216 @@
+---
+title: "Managed Auth"
+description: "Maintain authenticated browser sessions for agents"
+---
+
+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.
+
+Managed Auth works best when you want KERNEL to control the login flow and maintain the resulting session. If your end user supplies credentials while a task is running and your application or agent needs to control navigation and submission, use [Vaults + Credential Fill](/auth/credential-fill).
+
+## How it works
+
+
+
+ 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
+const auth = await kernel.auth.connections.create({
+ domain: 'netflix.com',
+ profile_name: 'netflix-user-123',
+});
+```
+
+```python Python
+auth = await kernel.auth.connections.create(
+ domain="netflix.com",
+ profile_name="netflix-user-123",
+)
+```
+
+```go Go
+auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
+ ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
+ Domain: "netflix.com",
+ ProfileName: "netflix-user-123",
+ },
+})
+if err != nil {
+ panic(err)
+}
+_ = 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 automatic reauthentication for supported credential-based flows.
+
+
+```typescript TypeScript
+const login = await kernel.auth.connections.login(auth.id);
+
+// Send user to login page
+console.log('Login URL:', login.hosted_url);
+
+// Stream state changes until the flow completes
+const events = await kernel.auth.connections.follow(auth.id);
+let finalState;
+
+for await (const event of events) {
+ if (event.event === 'managed_auth_state') {
+ finalState = event;
+ }
+}
+
+if (finalState?.flow_status === 'SUCCESS') {
+ console.log('Authenticated!');
+}
+```
+
+```python Python
+login = await kernel.auth.connections.login(auth.id)
+
+# Send user to login page
+print(f"Login URL: {login.hosted_url}")
+
+# Stream state changes until the flow completes
+events = await kernel.auth.connections.follow(auth.id)
+final_state = None
+
+async for event in events:
+ if event.event == "managed_auth_state":
+ final_state = event
+
+if final_state and final_state.flow_status == "SUCCESS":
+ print("Authenticated!")
+```
+
+```go Go
+login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{})
+if err != nil {
+ panic(err)
+}
+
+// Send user to login page
+fmt.Println("Login URL:", login.HostedURL)
+
+// Stream state changes until the flow completes
+events := client.Auth.Connections.FollowStreaming(ctx, auth.ID)
+authenticated := false
+
+for events.Next() {
+ event := events.Current()
+ if event.Event == "managed_auth_state" && event.FlowStatus == "SUCCESS" {
+ authenticated = true
+ }
+}
+if err := events.Err(); err != nil {
+ panic(err)
+}
+
+if authenticated {
+ fmt.Println("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, it loads the saved authentication state for every connected domain.
+
+
+```typescript TypeScript
+const browser = await kernel.browsers.create({
+ profile: { name: 'netflix-user-123' },
+ stealth: true,
+});
+
+// Navigate with the saved authentication state
+await page.goto('https://netflix.com');
+```
+
+```python Python
+browser = await kernel.browsers.create(
+ profile={"name": "netflix-user-123"},
+ stealth=True,
+)
+
+# Navigate with the saved authentication state
+await page.goto("https://netflix.com")
+```
+
+```go Go
+browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
+ Profile: shared.BrowserProfileParam{
+ Name: kernel.String("netflix-user-123"),
+ },
+ Stealth: kernel.Bool(true),
+})
+if err != nil {
+ panic(err)
+}
+_ = browser
+
+// Navigate with the saved authentication state
+_, err = client.Browsers.Playwright.Execute(ctx, browser.SessionID, kernel.BrowserPlaywrightExecuteParams{
+ Code: `await page.goto("https://netflix.com");`,
+})
+if err != nil {
+ panic(err)
+}
+```
+
+
+
+
+
+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
+
+
+
+ **Start here** - Simplest integration
+
+ 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
+
+ Mount `` on a route in your own app. Same flow as Hosted UI, rendered on your origin and trivial to restyle to match your brand.
+
+
+ **Custom Managed Auth UI** - Custom UI or headless
+
+ Build your own credential collection. Handle login fields, SSO buttons, MFA selection, and external actions (push notifications, security keys).
+
+
+
+
+## Why Managed Auth?
+
+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:
+
+- **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 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
+
+| Feature | Description |
+|---------|-------------|
+| **Encrypted credentials** | Values encrypted with per-organization keys |
+| **No credential exposure** | Never returned in API responses or passed to LLMs |
+| **Encrypted profiles** | Browser session state encrypted end-to-end |
+| **Isolated execution** | Each login runs in an isolated browser environment |
+
+## When to use Vaults + Credential Fill
+
+Use [Vaults + Credential Fill](/auth/credential-fill) when an end user owns the credentials, remains present during the task, and might need to respond to an authentication prompt mid-workflow. Your application or agent controls navigation, chooses the fields to fill, submits the form, and handles the site's response. KERNEL collects and stores sensitive values, then fills them without returning them through the api.
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 204ec541..decb0e7e 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -1,214 +1,70 @@
---
-title: "Overview"
-description: "Maintain authenticated browser sessions for agents"
+title: "Auth"
+description: "Choose how your browser agents authenticate and reuse signed-in sessions"
---
-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.
-
-if your agent would prefer to handle navigation and submission of login forms,
-use [vaults](/vaults/credentials). vaults let you collect sensitive credentials
-from a human and fill a browser form without passing the raw values back to the agent.
-
-## How It Works
-
-
-
- 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
-const auth = await kernel.auth.connections.create({
- domain: 'netflix.com',
- profile_name: 'netflix-user-123',
-});
-```
-
-```python Python
-auth = await kernel.auth.connections.create(
- domain="netflix.com",
- profile_name="netflix-user-123",
-)
-```
-
-```go Go
-auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
- ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
- Domain: "netflix.com",
- ProfileName: "netflix-user-123",
- },
-})
-if err != nil {
- panic(err)
-}
-_ = 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 automatic reauthentication for supported credential-based flows.
-
-
-```typescript TypeScript
-const login = await kernel.auth.connections.login(auth.id);
-
-// Send user to login page
-console.log('Login URL:', login.hosted_url);
-
-// Stream state changes until the flow completes
-const events = await kernel.auth.connections.follow(auth.id);
-let finalState;
-
-for await (const event of events) {
- if (event.event === 'managed_auth_state') {
- finalState = event;
- }
-}
-
-if (finalState?.flow_status === 'SUCCESS') {
- console.log('Authenticated!');
-}
-```
-
-```python Python
-login = await kernel.auth.connections.login(auth.id)
-
-# Send user to login page
-print(f"Login URL: {login.hosted_url}")
-
-# Stream state changes until the flow completes
-events = await kernel.auth.connections.follow(auth.id)
-final_state = None
-
-async for event in events:
- if event.event == "managed_auth_state":
- final_state = event
-
-if final_state and final_state.flow_status == "SUCCESS":
- print("Authenticated!")
-```
-
-```go Go
-login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{})
-if err != nil {
- panic(err)
-}
-
-// Send user to login page
-fmt.Println("Login URL:", login.HostedURL)
-
-// Stream state changes until the flow completes
-events := client.Auth.Connections.FollowStreaming(ctx, auth.ID)
-authenticated := false
-
-for events.Next() {
- event := events.Current()
- if event.Event == "managed_auth_state" && event.FlowStatus == "SUCCESS" {
- authenticated = true
- }
-}
-if err := events.Err(); err != nil {
- panic(err)
-}
-
-if authenticated {
- fmt.Println("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, it loads the saved authentication state for every connected domain.
-
-
-```typescript TypeScript
-const browser = await kernel.browsers.create({
- profile: { name: 'netflix-user-123' },
- stealth: true,
-});
-
-// Navigate with the saved authentication state
-await page.goto('https://netflix.com');
-```
-
-```python Python
-browser = await kernel.browsers.create(
- profile={"name": "netflix-user-123"},
- stealth=True,
-)
-
-# Navigate with the saved authentication state
-await page.goto("https://netflix.com")
-```
-
-```go Go
-browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
- Profile: shared.BrowserProfileParam{
- Name: kernel.String("netflix-user-123"),
- },
- Stealth: kernel.Bool(true),
-})
-if err != nil {
- panic(err)
-}
-_ = browser
-
-// Navigate with the saved authentication state
-_, err = client.Browsers.Playwright.Execute(ctx, browser.SessionID, kernel.BrowserPlaywrightExecuteParams{
- Code: `await page.goto("https://netflix.com");`,
-})
-if err != nil {
- panic(err)
-}
-```
-
-
-
-
-
-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
-
-
-
- **Start here** - Simplest integration
-
- 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
+most useful browser workflows begin behind a login. KERNEL gives you two ways to authenticate browser agents without returning stored sensitive values through the api or putting them in your agent prompt: delegate the login and session lifecycle to Managed Auth, or control the workflow yourself with Vaults + Credential Fill.
+
+## Choose an auth approach
+
+
+
+ **delegate the login lifecycle**
- Mount `` on a route in your own app. Same flow as Hosted UI, rendered on your origin and trivial to restyle to match your brand.
+ best when your application controls the credentials and you want KERNEL to navigate common login, sso, and mfa steps, save the authenticated state, and monitor the connection.
-
- **Full control** - Custom UI or headless
+
+ **control the login workflow**
- Build your own credential collection. Handle login fields, SSO buttons, MFA selection, and external actions (push notifications, security keys).
+ best when an end user owns the credentials. collect them during a task, then have your application or agent navigate, fill, submit, and handle the site's response.
+| | Managed Auth | Vaults + Credential Fill |
+| --- | --- | --- |
+| **best for** | developer- or organization-controlled credentials in repeatable or unattended automations | user-present workflows where an end user supplies credentials during a task |
+| **login navigation** | KERNEL | your application or agent |
+| **credential collection** | Managed Auth credential, Hosted UI, React component, or programmatic flow | KERNEL-hosted collection form or your trusted backend |
+| **form filling and submission** | KERNEL | KERNEL fills the selected fields; your application or agent submits the form |
+| **site response handling** | KERNEL | your application or agent |
+| **session state** | saved to a reusable profile | your workflow can save the resulting state to a profile |
+| **ongoing lifecycle** | health checks and eligible automatic reauthentication | your workflow decides when to authenticate again |
+
+
+ credential ownership is a useful starting point, but the main difference is who controls the login flow. Managed Auth can collect credentials from an end user. Vaults + Credential Fill is the lower-level option when your product needs to own navigation, submission, and recovery.
+
+
+## Common use cases
+
+### Use Managed Auth
-## Why Managed Auth?
+- your automation uses developer- or organization-controlled credentials.
+- the automation runs unattended or signs in repeatedly.
+- you want KERNEL to navigate common login, sso, and mfa flows.
+- you want health checks and eligible automatic reauthentication.
-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.
+### Use Vaults + Credential Fill
-The most valuable workflows live behind logins. Managed Auth provides:
+- your end user owns the credentials and is present during the task.
+- an authentication prompt can appear in the middle of a longer workflow.
+- your product needs to control when and how it asks for credentials.
+- your application or agent must own navigation, submission, and recovery.
-- **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 reauthentication for eligible credential-based flows
-- **Secure by default** - Credentials are encrypted at rest and never exposed in API responses or passed to LLMs
+## Understand the security boundary
-## Security
+KERNEL doesn't return stored sensitive fields in api responses or add them to model context. Credential Fill writes real values into the browser. Page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them after fill. Use the narrowest browser permissions that your workflow supports, and only attach a vault to sessions authorized to use all of its items.
-| Feature | Description |
-|---------|-------------|
-| **Encrypted credentials** | Values encrypted with per-organization keys |
-| **No credential exposure** | Never returned in API responses or passed to LLMs |
-| **Encrypted profiles** | Browser session state encrypted end-to-end |
-| **Isolated execution** | Each login runs in an isolated browser environment |
+## Reuse authenticated state
+
+[Profiles](/auth/profiles) persist cookies and local storage between browser sessions. Managed Auth saves successful logins to a profile automatically. A workflow using Vaults + Credential Fill can also save the resulting browser state to a profile when it needs to reuse that session.
+
+## Next steps
+
+
+
+ let KERNEL run the login flow and maintain the authenticated session.
+
+
+ collect credentials from a user, fill a browser form, and handle the login in your own workflow.
+
+
diff --git a/auth/profiles.mdx b/auth/profiles.mdx
index cb4d6efd..1e7cbe43 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 loads the saved authentication state for each connection.
+When you create a [Managed Auth connection](/auth/managed-auth), 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).
diff --git a/browsers/faq.mdx b/browsers/faq.mdx
index 0164bc2e..34b122cd 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) can keep sessions authenticated across runs for supported login flows.
+For workflows behind a login, [Managed Auth](/auth/managed-auth) 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 e870816c..fbce680e 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, 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](/auth/profiles) carries login state, including cookies and local storage, into a browser. Use [Managed Auth](/auth/managed-auth) 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.
@@ -275,7 +275,7 @@ A profile can only be loaded into a browser that was created without one, which
### Refresh on profile update
-Each browser loads the profile's data at the moment it's created, so re-saving that profile later doesn't reach browsers that are already running. With `refresh_on_profile_update` enabled, saving the profile — after a [Managed Auth](/auth/overview) login, for example — flushes every idle browser in the pool and replaces it with one that loads the updated data. Browsers that are currently acquired keep the data they started with.
+Each browser loads the profile's data at the moment it's created, so re-saving that profile later doesn't reach browsers that are already running. With `refresh_on_profile_update` enabled, saving the profile — after a [Managed Auth](/auth/managed-auth) login, for example — flushes every idle browser in the pool and replaces it with one that loads the updated data. Browsers that are currently acquired keep the data they started with.
It's enabled automatically when a browser pool is created with a profile or has its profile changed, and forced to `false` when the profile is removed (by passing `{ "id": "" }`). Set it to `false` to opt out.
diff --git a/browsers/use-vault-credentials-in-browser-agent.mdx b/browsers/use-vault-credentials-in-browser-agent.mdx
index 48187794..16987c64 100644
--- a/browsers/use-vault-credentials-in-browser-agent.mdx
+++ b/browsers/use-vault-credentials-in-browser-agent.mdx
@@ -1,8 +1,10 @@
---
-title: "Human-in-the-loop Secure Credential Collection and Form Filling"
+title: "Build an End-User Auth Workflow"
description: "Collect credentials from a human, then fill browser forms without passing raw values to your agent"
---
+this cookbook implements the [Vaults + Credential Fill](/auth/credential-fill) auth path. your end user supplies credentials through a secure collection form while your application or agent controls browser navigation, form submission, and recovery.
+
## What you need
- a `KERNEL_API_KEY`, set in the environment where your agent runs the cli. don't paste the key into its prompt.
diff --git a/changelog.mdx b/changelog.mdx
index 62ced8ff..ae3984bb 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -98,7 +98,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
- Kernel is now a connector in the [Vercel Connect](https://vercel.com/connect) registry: `vercel connect create kernel --connection-method mcp` pre-fills the MCP URL, auth type, and branding, and brokers per-user OAuth so no Kernel API key touches your app.
- Added a nested `proxy` object to the browser API, taking exactly one of `mode`, `id`, or `name`. Egress and stealth are now independent: an explicit [proxy](/proxies/overview) changes only where traffic exits and never toggles stealth or the CAPTCHA solver. `proxy_id` and `disable_default_proxy` are deprecated.
- Added [private browser networking](/browsers/private-networking): `network.private_hosts` names the hosts and CIDRs a browser or browser pool should reach directly through the session's own network — for a VPN or tunnel inside the VM — while everything else keeps using Kernel-managed egress.
-- Expanded [managed auth](/auth/overview) with a nested `browser` configuration on connections covering `stealth`, `proxy`, and `telemetry`, applied as the default for every browser a connection launches. Set `browser.stealth` to `false` to skip stealth mode and the CAPTCHA solver. The older `proxy`, `proxy_id`, and `browser_telemetry` fields are deprecated.
+- Expanded [managed auth](/auth/managed-auth) with a nested `browser` configuration on connections covering `stealth`, `proxy`, and `telemetry`, applied as the default for every browser a connection launches. Set `browser.stealth` to `false` to skip stealth mode and the CAPTCHA solver. The older `proxy`, `proxy_id`, and `browser_telemetry` fields are deprecated.
- Improved fingerprint coherence in [stealth-mode browsers](/browsers/bot-detection/stealth): the WebGL renderer persona now applies on GPU hosts as well as software-rendered ones, and storage quota, network information, and speech voices report plausible per-host values.
- Browser responses now include `profile_save_changes`, so you can tell which sessions loaded a [profile](/auth/profiles) read-write and coordinate a single writer.
- Fixed egress reliability issues: large downloads no longer truncate mid-body under backpressure, WebSocket and TURN traffic pass through unchanged, and origins that omit their intermediate certificate now verify the way Chrome does.
@@ -143,7 +143,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
- Released [`@onkernel/eve-extension`](https://github.com/kernel/eve-extension) v0.1.3, a Kernel-powered browser extension for Vercel's Eve agent.
- Published a [Codex plugin](https://github.com/kernel/skills) packaging for the Kernel [skills](https://github.com/kernel/skills) repo, so Codex users can install the full Kernel skill set the same way Claude Code and Cursor users can.
- Added a `get_telemetry` action to the [MCP server](/reference/mcp-server)'s `manage_browsers` tool for reading archived [browser telemetry](/browsers/telemetry/overview) — including for deleted sessions and events captured before telemetry was turned off — with category filters, time windows, and pagination.
-- Expanded [managed auth](/auth/overview): [browser telemetry](/browsers/telemetry/overview) is now configurable per connection and captured on timeline events, the health-check interval is adjustable from the dashboard, and health checks and their replays now appear on the connection timeline alongside logins and re-auths.
+- Expanded [managed auth](/auth/managed-auth): [browser telemetry](/browsers/telemetry/overview) is now configurable per connection and captured on timeline events, the health-check interval is adjustable from the dashboard, and health checks and their replays now appear on the connection timeline alongside logins and re-auths.
- Extended [`@onkernel/cua-agent`](https://github.com/kernel/cua) with Claude Opus 5 and Moonshot Kimi K3 computer-use providers, semantic browser waits (`waitFor` conditions instead of fixed sleeps), verified browser action plans, and gated Anthropic's native `computer_20260701` / `browser_20260701` tools by model.
- Added named markers to browser [replay recordings](/browsers/replays), exposed as MP4 chapters so playback jumps directly to key moments.
- Extended the [CLI](https://github.com/kernel/cli) `browser-pools` commands with telemetry configuration, matching `browsers create`/`update`.
@@ -172,7 +172,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
- Improved cold-start performance: reduced Chromium restart time, and cut ~5s off session creation for profile-restore paths by fixing a chromium-launcher port check that blocked on stale sockets.
- Set the default fill-rate for new [browser pools](/browsers/pools) created from the dashboard or [CLI](https://github.com/kernel/cli) to 25%, so pools warm up more predictably out of the box.
- [`refresh_on_profile_update`](/browsers/pools) now defaults to `true` when a browser pool has a profile attached, and auto-unsets when the profile is removed, so pooled sessions stay in sync with the underlying profile without manual configuration.
-- Expanded [managed auth](/auth/overview): the dashboard can now manage credential fields and TOTP secrets directly, and reauth now selects an already signed-in account on the SSO account chooser, so re-authentications can complete without human intervention when the browser is already signed in.
+- Expanded [managed auth](/auth/managed-auth): the dashboard can now manage credential fields and TOTP secrets directly, and reauth now selects an already signed-in account on the SSO account chooser, so re-authentications can complete without human intervention when the browser is already signed in.
- Shipped a Cmd+K command palette to the dashboard for jump-to-anywhere navigation.
- Published [`hermes-browser-plugin`](https://github.com/kernel/hermes-browser-plugin), a new Kernel cloud browser provider plugin for Hermes Agent.
- Improved [just-html](https://github.com/kernel/just-html) with section deeplinks, comment permalinks, and a public integration-discovery metadata endpoint, so shared docs are easier to navigate, link, and index by agents.
@@ -284,7 +284,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
- Exposed API key management in the Node, Python, and Go SDKs. Create, list, retrieve, update, and delete keys on `/org/api_keys` programmatically.
- Promoted `can_reauth_reason` on `ManagedAuth` to a typed enum (14 documented values like `requires_totp_without_secret`, `no_viable_plans`, `requires_external_action`) so SDK consumers can branch on it directly instead of string comparisons.
- Added an **Auto Re-Auth** / **Needs Human** capability chip to each row on the dashboard `/auth` page, with a tooltip mapping each `can_reauth_reason` to a human-readable explanation.
-- Added TOTP secret key support to [managed auth](/auth/overview) credentials, so one-time passwords are generated automatically during login and re-authentication. No human intervention required.
+- Added TOTP secret key support to [managed auth](/auth/managed-auth) credentials, so one-time passwords are generated automatically during login and re-authentication. No human intervention required.
- Updated the live view loading screen to a progress bar for clearer visual feedback during browser startup.
- The `/projects/*` endpoints are now routed under `/org/projects/*`. The previous paths are deprecated.
@@ -303,14 +303,14 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
- Added auto standby to browser pool instances — pools can now automatically suspend when idle and resume on the next incoming request, reducing costs without manual intervention.
- Launched new browser configuration options on `browsers.create()` and browser pool definitions: [`chrome_policy`](/browsers/pools/policy-json) and `start_url` for opening directly to a specified URL on launch. The corresponding `--start-url` flag is available in the [CLI](https://github.com/kernel/cli).
- Exposed full [Projects](/info/projects) CRUD in the public API, so projects can be created, updated, and deleted programmatically alongside the existing list endpoint.
-- Managed auth improvements: Added health check and automatic re-authentication controls to the [managed auth API](/auth/overview), letting you configure check intervals and reauth triggers per connection. Sessions are now automatically recorded — when a connection enters `NEEDS_AUTH` on the dashboard, a "View last login attempt" link routes directly to the session replay, and /auth rows now show a re-auth capability chip. Also, broader SSO and OAuth provider coverage, support for Google's two-step mobile prompt flow, per-connection post-login wait configuration (`post_login.wait_ms`), automatic SSO provider brand icons in auth dialogs, MFA alternatives displayed on the external action waiting screen, and a post-login browser refresh before the profile snapshot is captured for cleaner saved sessions.
+- Managed auth improvements: Added health check and automatic re-authentication controls to the [managed auth API](/auth/managed-auth), letting you configure check intervals and reauth triggers per connection. Sessions are now automatically recorded — when a connection enters `NEEDS_AUTH` on the dashboard, a "View last login attempt" link routes directly to the session replay, and /auth rows now show a re-auth capability chip. Also, broader SSO and OAuth provider coverage, support for Google's two-step mobile prompt flow, per-connection post-login wait configuration (`post_login.wait_ms`), automatic SSO provider brand icons in auth dialogs, MFA alternatives displayed on the external action waiting screen, and a post-login browser refresh before the profile snapshot is captured for cleaner saved sessions.
- Extended `proxy.check()` with an optional `url` parameter for testing reachability against a specific target domain before assigning the proxy. This is useful for catching proxies that pass generic health checks but are blocked on your target site.
- End of life'd persistent browsers. If you were using persistence, we suggest [`timeout_seconds`](/browsers/termination) with [Profiles](/auth/profiles).
## Documentation updates
- Added a new [hCaptcha](/browsers/bot-detection/hcaptcha) page documenting beta support for hCaptcha solving.
-- Refreshed [managed auth](/auth/overview) documentation for May 2026: new dedicated [connection lifecycle](/auth/connection-lifecycle) page covering health checks and re-authentication, a shared [connection configuration](/auth/configuration) reference, documented `success_url` / `error_url` query parameters for the [hosted UI](/auth/hosted-ui), [`start_url`](/browsers/create-a-browser) references across browser and pool docs, a reorganized sidebar, and new FAQ entries for short-session reauth and multi-step login forms.
+- Refreshed [managed auth](/auth/managed-auth) documentation for May 2026: new dedicated [connection lifecycle](/auth/connection-lifecycle) page covering health checks and re-authentication, a shared [connection configuration](/auth/configuration) reference, documented `success_url` / `error_url` query parameters for the [hosted UI](/auth/hosted-ui), [`start_url`](/browsers/create-a-browser) references across browser and pool docs, a reorganized sidebar, and new FAQ entries for short-session reauth and multi-step login forms.
- Clarified that managed residential proxy IPs are stable within a session but are not guaranteed to persist across sessions.
- Updated the [Yutori integration guide](/integrations/computer-use/yutori) to Navigator n1.5.
- Clarified that profile updates do not propagate to idle browser pool instances — pools must be recycled for profile changes to take effect.
@@ -319,11 +319,11 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
## Product updates
-- Released [`@onkernel/managed-auth-react`](https://github.com/kernel/managed-auth-react), a drop-in React component library for embedding [managed auth](/auth/overview) flows directly into your app. Ship a Kernel-powered login experience without rebuilding the credential entry, MFA, and SSO dialogs yourself.
+- Released [`@onkernel/managed-auth-react`](https://github.com/kernel/managed-auth-react), a drop-in React component library for embedding [managed auth](/auth/managed-auth) flows directly into your app. Ship a Kernel-powered login experience without rebuilding the credential entry, MFA, and SSO dialogs yourself.
- Added a [Docker Sandboxes mixin kit](https://github.com/kernel/docker-sbx-kit) for running Kernel inside Docker's AI sandboxes (`sbx`). The kit ships the [Kernel CLI](https://github.com/kernel/cli), Claude Code [skills](https://github.com/kernel/skills), and a proxy-managed auth header pre-configured, so agents inside the sandbox can call the Kernel API while your real `KERNEL_API_KEY` stays on the host.
- Extended [Projects](/info/projects): profile, browser pool, extension, and credential names are now scoped per-project, and the `GET /projects` API and dashboard project selector support server-side search and pagination.
-- Made the [1Password](/integrations/1password) credential dropdown searchable in [managed auth](/auth/overview) dialogs.
-- Improved [managed auth](/auth/overview) autofill reliability on multi-step sign-in pages.
+- Made the [1Password](/integrations/1password) credential dropdown searchable in [managed auth](/auth/managed-auth) dialogs.
+- Improved [managed auth](/auth/managed-auth) autofill reliability on multi-step sign-in pages.
- Added `-o json` output to `kernel browsers playwright execute` in the [CLI](https://github.com/kernel/cli), matching the other `browsers` subcommands, so script runs can be piped into other tooling.
## Documentation updates
@@ -397,7 +397,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
## Documentation updates
-- Documented MFA token auto-retry behavior for [managed auth](/auth/overview) sessions.
+- Documented MFA token auto-retry behavior for [managed auth](/auth/managed-auth) sessions.
- Added a new [policy.json](/browsers/pools/policy-json) page to the Reserved Browsers documentation.
- Clarified that [profiles](/auth/profiles) can have multiple auth connections.
- Added a Headful + GPU acceleration option to the [pricing calculator](/info/pricing#pricing-calculator).
@@ -417,7 +417,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
- Added [API rate limiting](/info/pricing#rate-limiting) documentation.
- Documented the [`disable_default_proxy`](/browsers/bot-detection/stealth) option for stealth browsers.
- Updated [live view embedding](/browsers/live-view) docs with iframe focus tips, clipboard sharing guidance, and CSP configuration.
-- Documented [managed auth re-authentication triggers](/auth/overview).
+- Documented [managed auth re-authentication triggers](/auth/managed-auth).
@@ -433,7 +433,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
## Documentation updates
- Added an FAQ entry for [debugging managed auth sessions](/auth/faq#how-do-i-debug-a-managed-auth-session).
-- Updated [Managed Auth](/auth/overview) documentation to cover CUA support, the PATCH endpoint, and auto-allowed SSO domains.
+- Updated [Managed Auth](/auth/managed-auth) documentation to cover CUA support, the PATCH endpoint, and auto-allowed SSO domains.
@@ -450,7 +450,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
- Added new docs for [GPU acceleration](/browsers/gpu-acceleration).
- Added [ZIP code targeting](/proxies/residential) documentation for residential proxies.
- Clarified [download behavior](/browsers/file-io) for programmatic file downloads.
-- Reorganized documentation to make [Managed Auth](/auth/overview) and [Browser Pools](/browsers/pools) more prominent and accessible.
+- Reorganized documentation to make [Managed Auth](/auth/managed-auth) and [Browser Pools](/browsers/pools) more prominent and accessible.
@@ -476,7 +476,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
- Added support for [mobile and tablet viewports](/browsers/viewport), enabling browser automation at phone and tablet screen sizes.
- Added a `kernel status` command to the [CLI](https://github.com/kernel/cli) for checking API and service health at a glance.
- Added a `--force` flag to `kernel browsers update` for [resizing the viewport](/browsers/viewport) during an active recording, which gracefully stops and restarts the recording.
-- Improved [Managed Auth](/auth/overview) MFA handling by resolving MFA options by label, type, or display string for more reliable multi-factor authentication flows.
+- Improved [Managed Auth](/auth/managed-auth) MFA handling by resolving MFA options by label, type, or display string for more reliable multi-factor authentication flows.
- Enhanced auth connection output in the [CLI](https://github.com/kernel/cli) with richer details from `kernel auth connections get` and `kernel auth connections list`.
- Added a Pool column and `--query` flag to `kernel browsers list` in the [CLI](https://github.com/kernel/cli) for easier filtering and identification of pooled browsers.
- Updated the Anthropic computer use [template](https://github.com/kernel/cli/tree/main/pkg/templates) to default to use claude-sonnet-4-6 for improved agent performance.
@@ -518,7 +518,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
## Product updates
- Added mouse position tracking to the [CLI](https://github.com/kernel/cli), enabling retrieval of current mouse coordinates.
- Updated Yutori computer use [templates](https://github.com/kernel/cli/tree/main/pkg/templates) to support the n1-latest model for improved agent performance.
-- Updated [Managed Auth](/auth/overview) by adding subdomain-based sign-in support, better error handling for `401 Unauthorized` and `410 Gone` responses, and enhanced error messaging with structured error codes and actionable guidance.
+- Updated [Managed Auth](/auth/managed-auth) by adding subdomain-based sign-in support, better error handling for `401 Unauthorized` and `410 Gone` responses, and enhanced error messaging with structured error codes and actionable guidance.
- Improved browser display by auto-toggling Chromium app mode on small viewports for a cleaner, more immersive experience.
- Fixed screen resize accuracy by removing unnecessary rounding in `ChangeScreenSize` to ensure pixel-perfect display dimensions.
@@ -530,7 +530,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
## Product updates
- Launched [Web Bot Auth](/browsers/bot-detection/web-bot-auth) in partnership with Vercel, enabling agents to cryptographically sign requests and prove they're legitimate instead of getting blocked by bot detection.
-- Released [Managed Auth](/auth/overview), simplifying authentication by securely logging into any site without custom auth flows or exposing credentials to the LLM, and maintaining up-to-date credentials.
+- Released [Managed Auth](/auth/managed-auth), simplifying authentication by securely logging into any site without custom auth flows or exposing credentials to the LLM, and maintaining up-to-date credentials.
- Added a `POST /computer/batch` [endpoint](https://kernel.sh/docs/api-reference/browsers/execute-a-batch-of-computer-actions-sequentially) for executing multiple computer actions in a single API call, reducing round-trip latency for complex automations.
- Improved the [CLI](https://github.com/onkernel/cli) by adding new commands for managing auth connections, supporting `-o json` output for `kernel ssh --setup-only`, allowing pool names as positional arguments in `kernel browser-pools create`, and enabling file exclusions when publishing extensions.
- Improved input reliability with context-aware timing in key press and mouse drag operations.
@@ -538,7 +538,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
## Documentation updates
- Clarified [pricing](/info/pricing) for headful browser sessions.
-- Added comprehensive [Managed Auth](/auth/overview) documentation, including billing guidance.
+- Added comprehensive [Managed Auth](/auth/managed-auth) documentation, including billing guidance.
diff --git a/docs.json b/docs.json
index 6cab1c55..7850c8af 100644
--- a/docs.json
+++ b/docs.json
@@ -6,7 +6,7 @@
{ "source": "/careers/backend-engineer", "destination": "https://jobs.ashbyhq.com/usekernel" },
{ "source": "/careers/engineer-new-grad", "destination": "https://jobs.ashbyhq.com/usekernel" },
{ "source": "/careers/customer-engineer", "destination": "https://jobs.ashbyhq.com/usekernel" },
- { "source": "/auth/agent/overview", "destination": "/auth/overview" },
+ { "source": "/auth/agent/overview", "destination": "/auth/managed-auth" },
{ "source": "/auth/agent/hosted-ui", "destination": "/auth/hosted-ui" },
{ "source": "/auth/agent/programmatic", "destination": "/auth/programmatic" },
{ "source": "/auth/agent/faq", "destination": "/auth/faq" },
@@ -117,24 +117,30 @@
"pages": [
"auth/overview",
{
- "group": "Integration Types",
+ "group": "Managed Auth",
"pages": [
+ "auth/managed-auth",
"auth/hosted-ui",
"auth/react",
- "auth/programmatic"
+ "auth/programmatic",
+ "auth/configuration",
+ "auth/connection-lifecycle",
+ "auth/credentials",
+ "auth/faq"
]
},
- "auth/configuration",
- "auth/connection-lifecycle",
- "auth/credentials",
- "auth/profiles",
- "auth/faq"
+ {
+ "group": "Vaults + Credential Fill",
+ "pages": [
+ "auth/credential-fill",
+ "vaults/credentials",
+ "vaults/fill",
+ "browsers/use-vault-credentials-in-browser-agent"
+ ]
+ },
+ "auth/profiles"
]
},
- {
- "group": "Vaults",
- "pages": ["vaults/overview", "vaults/credentials", "vaults/fill"]
- },
"config-registry",
"info/api-keys",
"info/audit-logs",
@@ -227,6 +233,7 @@
"icon": "/images/integration-icons/payments.svg",
"pages": [
"integrations/payments/overview",
+ "vaults/overview",
"integrations/payments/stripe-link",
"integrations/payments/agentcard"
]
diff --git a/index.mdx b/index.mdx
index fd38ca27..a9b63387 100644
--- a/index.mdx
+++ b/index.mdx
@@ -12,7 +12,7 @@ We build crazy fast, open source infra for AI agents to access the internet. Tru
We spin up cloud browsers in <30ms with GPU acceleration when needed.
- We manage auth for your agents so you don't have to.
+ Choose managed login flows or secure credential fill for browser agents.
We solve CAPTCHAs and manage residential proxies to help you see fewer of them.
@@ -75,4 +75,4 @@ kernel invoke my-agent my-task --payload '{"url": "https://example.com"}'
### scaling
-[browser pools](/browsers/pools) keep browsers ready to use and pre-configured, so you skip start-up latency on every task and idle browsers aren't billed. reach for them once you're running the same workload repeatedly, need low-latency acquisition, or are scaling steady, high-frequency traffic — on-demand `browsers.create()` stays the right call for occasional, bursty, or one-off work.
\ No newline at end of file
+[browser pools](/browsers/pools) keep browsers ready to use and pre-configured, so you skip start-up latency on every task and idle browsers aren't billed. reach for them once you're running the same workload repeatedly, need low-latency acquisition, or are scaling steady, high-frequency traffic — on-demand `browsers.create()` stays the right call for occasional, bursty, or one-off work.
diff --git a/integrations/1password.mdx b/integrations/1password.mdx
index 54e67b25..ef06c06a 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 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.
+Connect 1Password to use credentials from your existing vaults with [Managed Auth](/auth/managed-auth). You don't need to recreate credentials in Kernel because 1Password items are discovered by domain matching.
## How It Works
diff --git a/integrations/vercel/eve-extension.mdx b/integrations/vercel/eve-extension.mdx
index b59746eb..2e3ef1e3 100644
--- a/integrations/vercel/eve-extension.mdx
+++ b/integrations/vercel/eve-extension.mdx
@@ -27,7 +27,7 @@ Vercel Connect is the recommended path because:
- No key touches your app, environment, or the model.
- Each user authenticates as themselves with a one-time consent that's cached afterward.
-- Per-user identity is a good fit for Kernel's [managed auth](/auth/overview).
+- Per-user identity is a good fit for Kernel's [managed auth](/auth/managed-auth).
**1. Install** the extension:
@@ -72,7 +72,7 @@ Once mounted, the agent has the following tools, namespaced under your mount (e.
- **`manage_browsers`**: create, list, get, and delete browser sessions. Returns a `session_id` and a `live_view_url` you can watch or take over.
- **`execute_playwright_code`**: run Playwright against the live page to read, navigate, click, or type.
- **`computer_action`**: human-like mouse, keyboard, and screenshot controls for the same session.
-- **`manage_auth_connections`**: Kernel's [managed auth](/auth/overview), so the agent logs into sites through a stored connection or a hosted login flow instead of typing credentials into the page.
+- **`manage_auth_connections`**: Kernel's [managed auth](/auth/managed-auth), so the agent logs into sites through a stored connection or a hosted login flow instead of typing credentials into the page.
- **`manage_profiles`**: create and reuse browser [profiles](/auth/profiles) (persistent cookies, logins, storage).
- **`manage_proxies`**: create and attach [proxies](/proxies/overview) (datacenter, ISP, residential, mobile) with geo-targeting.
- **`manage_replays`**: start, stop, and list video replay recordings for a session, so you can capture what the agent did as an MP4. Requires a paid Kernel plan.
@@ -208,7 +208,7 @@ export default defineMcpClientConnection({
Log agents into sites without handling credentials
diff --git a/integrations/vercel/foreman.mdx b/integrations/vercel/foreman.mdx
index 023c50cb..4da727ae 100644
--- a/integrations/vercel/foreman.mdx
+++ b/integrations/vercel/foreman.mdx
@@ -83,4 +83,4 @@ Finish by running pnpm validate and confirming 0 errors and 0 warnings, then run
- [Eve Extension](/integrations/vercel/eve-extension)
- [Vercel Marketplace Integration](/integrations/vercel/marketplace)
-- [Managed Auth](/auth/overview)
+- [Managed Auth](/auth/managed-auth)
diff --git a/introduction/create.mdx b/introduction/create.mdx
index 11700c97..9d698a18 100644
--- a/introduction/create.mdx
+++ b/introduction/create.mdx
@@ -83,7 +83,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 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).
+ 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/managed-auth).
diff --git a/proxies/datacenter.mdx b/proxies/datacenter.mdx
index 969413a7..46e623a3 100644
--- a/proxies/datacenter.mdx
+++ b/proxies/datacenter.mdx
@@ -8,7 +8,7 @@ Datacenter proxies use IP addresses assigned from datacenter servers to route yo
Datacenter proxies use **rotating exit IPs** — a new exit IP is assigned per request, so different requests within the same browser session can exit through different IPs.
-If you need a stable IP across requests and sessions (e.g. for IP allowlists or [managed auth](/auth/overview) health checks), use an [ISP proxy](/proxies/isp) instead. See [IP rotation behavior across proxy types](/proxies/overview) for the full comparison.
+If you need a stable IP across requests and sessions (e.g. for IP allowlists or [managed auth](/auth/managed-auth) health checks), use an [ISP proxy](/proxies/isp) instead. See [IP rotation behavior across proxy types](/proxies/overview) for the full comparison.
## Configuration
diff --git a/proxies/isp.mdx b/proxies/isp.mdx
index 1bb9322e..c5f22e89 100644
--- a/proxies/isp.mdx
+++ b/proxies/isp.mdx
@@ -8,7 +8,7 @@ ISP (Internet Service Provider) proxies are hosted on datacenter infrastructure
ISP proxies provide a **static exit IP that persists across sessions** — every tab, request, reconnection, and future browser session attached to this proxy exits through the same IP. The IP only changes in rare ISP-initiated replacement events.
-This makes ISP proxies suitable for use cases that require a stable IP, such as IP allowlists or [managed auth](/auth/overview) health checks. For comparison with other proxy types, see [IP rotation behavior across proxy types](/proxies/overview).
+This makes ISP proxies suitable for use cases that require a stable IP, such as IP allowlists or [managed auth](/auth/managed-auth) health checks. For comparison with other proxy types, see [IP rotation behavior across proxy types](/proxies/overview).
## Configuration
diff --git a/proxies/overview.mdx b/proxies/overview.mdx
index 3cae5c04..f01762bd 100644
--- a/proxies/overview.mdx
+++ b/proxies/overview.mdx
@@ -21,7 +21,7 @@ Kernel-provided proxies are unmetered and not billed, subject to the fair use ru
-ISP proxies provide a **static exit IP that persists across sessions** — every browser session attached to the proxy exits through the same IP, and it only changes in rare ISP-initiated replacement events. This makes them suitable for IP allowlists or [managed auth](/auth/overview) health checks that must egress from a single IP.
+ISP proxies provide a **static exit IP that persists across sessions** — every browser session attached to the proxy exits through the same IP, and it only changes in rare ISP-initiated replacement events. This makes them suitable for IP allowlists or [managed auth](/auth/managed-auth) health checks that must egress from a single IP.
Datacenter proxies use **rotating exit IPs** — a new exit IP is assigned per request, so different requests within the same browser session can exit through different IPs. For a stable IP across requests and sessions, use an ISP proxy or a [custom (BYO) proxy](/proxies/custom) pointed at infrastructure you control.
diff --git a/reference/cli/managed-auth.mdx b/reference/cli/managed-auth.mdx
index 5dfcd239..49caa2af 100644
--- a/reference/cli/managed-auth.mdx
+++ b/reference/cli/managed-auth.mdx
@@ -2,10 +2,10 @@
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).
+Manage [managed auth](/auth/managed-auth) 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 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.
+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/managed-auth) 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.
diff --git a/vaults/credentials.mdx b/vaults/credentials.mdx
index 5dda6277..44e896fd 100644
--- a/vaults/credentials.mdx
+++ b/vaults/credentials.mdx
@@ -3,13 +3,13 @@ title: "Credential Items"
description: "Collect and update encrypted credentials, then fill selected fields in a vault-attached browser"
---
-use a `credential` item for usernames, passwords, totp generators, and other non-payment credentials. it belongs directly to a [vault](/vaults/overview); you don't need a wallet or an external credential provider.
+use a `credential` item for usernames, passwords, totp generators, and other non-payment credentials. it belongs directly to a [vault](/vaults/overview); you don't need a wallet or an external credential provider. credential items power the [Vaults + Credential Fill](/auth/credential-fill) path under Auth.
use `wallet` and `card` items for credit card numbers, security codes, and expiration dates. don't store, collect, or fill payment-card data through credential items.
-credential items store values and support explicit [browser fill](/vaults/fill). your application or agent still handles navigation, submission, and the site's response. choose [managed auth](/auth/overview) instead when you want KERNEL to run login flows and maintain authenticated sessions.
+credential items store values and support explicit [browser fill](/vaults/fill). your application or agent still handles navigation, submission, and the site's response. choose [Managed Auth](/auth/managed-auth) instead when you want KERNEL to run login flows and maintain authenticated sessions.
## Define an item
diff --git a/vaults/fill.mdx b/vaults/fill.mdx
index 64b83208..bc0d3f13 100644
--- a/vaults/fill.mdx
+++ b/vaults/fill.mdx
@@ -3,7 +3,7 @@ title: "Fill Browser Fields"
description: "Map vault fields to browser inputs without returning their values to your application"
---
-invoke an item's `fill` operation to write selected values into an attached browser. your request contains field names and css selectors, not credential values. the result reports outcomes without returning the values.
+invoke an item's `fill` operation to write selected values into an attached browser. your request contains field names and css selectors, not credential values. the result reports outcomes without returning the values. fill is the credential injection step in the [Vaults + Credential Fill](/auth/credential-fill) auth path.
`fill` reads credentials from a ready KERNEL credential item. if another vault
From afbc70ae01a0543799b431c4a6801dbe601cad80 Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Tue, 15 Sep 2026 23:23:47 +0000
Subject: [PATCH 02/27] Prioritize credential fill in auth docs
---
auth/credential-fill.mdx | 2 +-
auth/managed-auth.mdx | 2 +-
auth/overview.mdx | 48 ++++++++++++++++++++--------------------
docs.json | 18 +++++++--------
4 files changed, 35 insertions(+), 35 deletions(-)
diff --git a/auth/credential-fill.mdx b/auth/credential-fill.mdx
index cf14b5b5..f0d716a8 100644
--- a/auth/credential-fill.mdx
+++ b/auth/credential-fill.mdx
@@ -1,5 +1,5 @@
---
-title: "Vaults + Credential Fill"
+title: "Overview"
description: "Collect end-user credentials and inject them into browser forms while controlling the login workflow"
---
diff --git a/auth/managed-auth.mdx b/auth/managed-auth.mdx
index a7c77aa6..062bb6cd 100644
--- a/auth/managed-auth.mdx
+++ b/auth/managed-auth.mdx
@@ -1,5 +1,5 @@
---
-title: "Managed Auth"
+title: "Overview"
description: "Maintain authenticated browser sessions for agents"
---
diff --git a/auth/overview.mdx b/auth/overview.mdx
index decb0e7e..244f5392 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -1,5 +1,5 @@
---
-title: "Auth"
+title: "Overview"
description: "Choose how your browser agents authenticate and reuse signed-in sessions"
---
@@ -8,27 +8,27 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
## Choose an auth approach
-
- **delegate the login lifecycle**
-
- best when your application controls the credentials and you want KERNEL to navigate common login, sso, and mfa steps, save the authenticated state, and monitor the connection.
-
**control the login workflow**
best when an end user owns the credentials. collect them during a task, then have your application or agent navigate, fill, submit, and handle the site's response.
+
+ **delegate the login lifecycle**
+
+ best when your application controls the credentials and you want KERNEL to navigate common login, sso, and mfa steps, save the authenticated state, and monitor the connection.
+
-| | Managed Auth | Vaults + Credential Fill |
+| | Vaults + Credential Fill | Managed Auth |
| --- | --- | --- |
-| **best for** | developer- or organization-controlled credentials in repeatable or unattended automations | user-present workflows where an end user supplies credentials during a task |
-| **login navigation** | KERNEL | your application or agent |
-| **credential collection** | Managed Auth credential, Hosted UI, React component, or programmatic flow | KERNEL-hosted collection form or your trusted backend |
-| **form filling and submission** | KERNEL | KERNEL fills the selected fields; your application or agent submits the form |
-| **site response handling** | KERNEL | your application or agent |
-| **session state** | saved to a reusable profile | your workflow can save the resulting state to a profile |
-| **ongoing lifecycle** | health checks and eligible automatic reauthentication | your workflow decides when to authenticate again |
+| **best for** | user-present workflows where an end user supplies credentials during a task | developer- or organization-controlled credentials in repeatable or unattended automations |
+| **login navigation** | your application or agent | KERNEL |
+| **credential collection** | KERNEL-hosted collection form or your trusted backend | Managed Auth credential, Hosted UI, React component, or programmatic flow |
+| **form filling and submission** | KERNEL fills the selected fields; your application or agent submits the form | KERNEL |
+| **site response handling** | your application or agent | KERNEL |
+| **session state** | your workflow can save the resulting state to a profile | saved to a reusable profile |
+| **ongoing lifecycle** | your workflow decides when to authenticate again | health checks and eligible automatic reauthentication |
credential ownership is a useful starting point, but the main difference is who controls the login flow. Managed Auth can collect credentials from an end user. Vaults + Credential Fill is the lower-level option when your product needs to own navigation, submission, and recovery.
@@ -36,13 +36,6 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
## Common use cases
-### Use Managed Auth
-
-- your automation uses developer- or organization-controlled credentials.
-- the automation runs unattended or signs in repeatedly.
-- you want KERNEL to navigate common login, sso, and mfa flows.
-- you want health checks and eligible automatic reauthentication.
-
### Use Vaults + Credential Fill
- your end user owns the credentials and is present during the task.
@@ -50,6 +43,13 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
- your product needs to control when and how it asks for credentials.
- your application or agent must own navigation, submission, and recovery.
+### Use Managed Auth
+
+- your automation uses developer- or organization-controlled credentials.
+- the automation runs unattended or signs in repeatedly.
+- you want KERNEL to navigate common login, sso, and mfa flows.
+- you want health checks and eligible automatic reauthentication.
+
## Understand the security boundary
KERNEL doesn't return stored sensitive fields in api responses or add them to model context. Credential Fill writes real values into the browser. Page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them after fill. Use the narrowest browser permissions that your workflow supports, and only attach a vault to sessions authorized to use all of its items.
@@ -61,10 +61,10 @@ KERNEL doesn't return stored sensitive fields in api responses or add them to mo
## Next steps
-
- let KERNEL run the login flow and maintain the authenticated session.
-
collect credentials from a user, fill a browser form, and handle the login in your own workflow.
+
+ let KERNEL run the login flow and maintain the authenticated session.
+
diff --git a/docs.json b/docs.json
index 7850c8af..eb4d2504 100644
--- a/docs.json
+++ b/docs.json
@@ -116,6 +116,15 @@
"group": "Auth",
"pages": [
"auth/overview",
+ {
+ "group": "Vaults + Credential Fill",
+ "pages": [
+ "auth/credential-fill",
+ "vaults/credentials",
+ "vaults/fill",
+ "browsers/use-vault-credentials-in-browser-agent"
+ ]
+ },
{
"group": "Managed Auth",
"pages": [
@@ -129,15 +138,6 @@
"auth/faq"
]
},
- {
- "group": "Vaults + Credential Fill",
- "pages": [
- "auth/credential-fill",
- "vaults/credentials",
- "vaults/fill",
- "browsers/use-vault-credentials-in-browser-agent"
- ]
- },
"auth/profiles"
]
},
From 31721b598b189fda949e8f21d05e080f81bc2793 Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Tue, 15 Sep 2026 23:31:00 +0000
Subject: [PATCH 03/27] Restore shared docs to their original navigation
---
auth/overview.mdx | 4 ++--
docs.json | 10 +++++-----
2 files changed, 7 insertions(+), 7 deletions(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 244f5392..1f6966c6 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -61,8 +61,8 @@ KERNEL doesn't return stored sensitive fields in api responses or add them to mo
## Next steps
-
- collect credentials from a user, fill a browser form, and handle the login in your own workflow.
+
+ collect end-user credentials and control navigation, form submission, and recovery in your own workflow.
let KERNEL run the login flow and maintain the authenticated session.
diff --git a/docs.json b/docs.json
index eb4d2504..de2ea7ad 100644
--- a/docs.json
+++ b/docs.json
@@ -119,10 +119,7 @@
{
"group": "Vaults + Credential Fill",
"pages": [
- "auth/credential-fill",
- "vaults/credentials",
- "vaults/fill",
- "browsers/use-vault-credentials-in-browser-agent"
+ "auth/credential-fill"
]
},
{
@@ -141,6 +138,10 @@
"auth/profiles"
]
},
+ {
+ "group": "Vaults",
+ "pages": ["vaults/overview", "vaults/credentials", "vaults/fill"]
+ },
"config-registry",
"info/api-keys",
"info/audit-logs",
@@ -233,7 +234,6 @@
"icon": "/images/integration-icons/payments.svg",
"pages": [
"integrations/payments/overview",
- "vaults/overview",
"integrations/payments/stripe-link",
"integrations/payments/agentcard"
]
From b11778a5616f67b8fc7abcf0dfe31d2ac8a1722c Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Tue, 15 Sep 2026 23:38:27 +0000
Subject: [PATCH 04/27] Connect credential fill overview to its cookbook
---
auth/credential-fill.mdx | 4 +++-
browsers/use-vault-credentials-in-browser-agent.mdx | 2 +-
2 files changed, 4 insertions(+), 2 deletions(-)
diff --git a/auth/credential-fill.mdx b/auth/credential-fill.mdx
index f0d716a8..ed18695a 100644
--- a/auth/credential-fill.mdx
+++ b/auth/credential-fill.mdx
@@ -5,6 +5,8 @@ description: "Collect end-user credentials and inject them into browser forms wh
Vaults + Credential Fill gives your application or agent direct control over authentication. Use it when an end user supplies credentials during a task and your workflow needs to own navigation, submission, and recovery.
+start with the [end-user auth workflow cookbook](/browsers/use-vault-credentials-in-browser-agent) for an end-to-end example of secure collection, browser attachment, credential fill, form submission, and cleanup.
+
KERNEL collects credential values or accepts them from a trusted backend, encrypts them in a credential item, and fills selected browser fields without including the values in the fill request or response. Your application or agent decides where to navigate, which fields to fill, when to submit, and how to handle the site's response.
@@ -27,7 +29,7 @@ Choose [Managed Auth](/auth/managed-auth) instead when you want KERNEL to run th
- create a vault for each end user or credential-sharing boundary. A vault groups the items that an attached browser session can use.
+ create a [vault](/vaults/overview) for each end user or credential-sharing boundary. A vault groups the items that an attached browser session can use.
define a [credential item](/vaults/credentials), then collect values through a KERNEL-hosted form or copy them from a trusted backend. Sensitive values aren't returned by the vault api.
diff --git a/browsers/use-vault-credentials-in-browser-agent.mdx b/browsers/use-vault-credentials-in-browser-agent.mdx
index 16987c64..9883d080 100644
--- a/browsers/use-vault-credentials-in-browser-agent.mdx
+++ b/browsers/use-vault-credentials-in-browser-agent.mdx
@@ -3,7 +3,7 @@ title: "Build an End-User Auth Workflow"
description: "Collect credentials from a human, then fill browser forms without passing raw values to your agent"
---
-this cookbook implements the [Vaults + Credential Fill](/auth/credential-fill) auth path. your end user supplies credentials through a secure collection form while your application or agent controls browser navigation, form submission, and recovery.
+this is the end-to-end cookbook for the [Vaults + Credential Fill](/auth/credential-fill) auth path. it covers secure collection, browser attachment, credential fill, form submission, and cleanup while your application or agent controls the workflow.
## What you need
From 9720556969bc8e6bf59c4139cb4b956ccb25bd46 Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Tue, 15 Sep 2026 23:49:31 +0000
Subject: [PATCH 05/27] Document existing vault credential sync
---
auth/credential-fill.mdx | 2 +-
auth/credential-fill/existing-vault.mdx | 188 ++++++++++++++++++++++++
docs.json | 3 +-
vaults/credentials.mdx | 2 +
4 files changed, 193 insertions(+), 2 deletions(-)
create mode 100644 auth/credential-fill/existing-vault.mdx
diff --git a/auth/credential-fill.mdx b/auth/credential-fill.mdx
index ed18695a..6cd44209 100644
--- a/auth/credential-fill.mdx
+++ b/auth/credential-fill.mdx
@@ -47,7 +47,7 @@ Choose [Managed Auth](/auth/managed-auth) instead when you want KERNEL to run th
## Credential sources
-you can collect values from an end user with KERNEL's hosted collection form or copy them from a credential store that your trusted backend can read. Both paths create the same ready credential item and use the same fill operation.
+you can collect values from an end user with KERNEL's hosted collection form or [copy them from an existing credential vault](/auth/credential-fill/existing-vault) that your trusted backend can read. Both paths create the same ready credential item and use the same fill operation.
Today, copying values stores an encrypted KERNEL copy. Credential Fill doesn't accept raw values or a third-party vault reference in the fill request.
diff --git a/auth/credential-fill/existing-vault.mdx b/auth/credential-fill/existing-vault.mdx
new file mode 100644
index 00000000..ed1afee9
--- /dev/null
+++ b/auth/credential-fill/existing-vault.mdx
@@ -0,0 +1,188 @@
+---
+title: "Use an Existing Credential Vault"
+description: "Copy credentials from an existing vault into KERNEL for browser fill"
+---
+
+keep an existing credential vault as your source of truth while using KERNEL to fill browser forms. Your trusted backend reads the source credential, copies it into a KERNEL credential item, and updates or deletes that copy as the source changes.
+
+
+ Credential Fill doesn't currently read directly from a third-party vault or accept a provider reference in a fill request. KERNEL stores an encrypted copy of the values. Your backend is responsible for synchronization and deletion.
+
+
+## How it works
+
+
+
+ read the credential with the third-party vault's server-side sdk. Keep provider tokens and returned values in your trusted backend.
+
+
+ create a KERNEL [credential item](/vaults/credentials) with the same field names and values. Mark secrets and any identifiers that don't need a read path as sensitive.
+
+
+ attach the KERNEL vault when you create the browser, then invoke [fill](/vaults/fill) with field names and selectors. The fill request and response don't contain the stored values.
+
+
+ update the KERNEL item after the source rotates. Delete the KERNEL item when your retention policy no longer permits KERNEL to hold the copy.
+
+
+
+## Copy a credential
+
+the following example reads an account credential from aws secrets manager, validates it, and copies it into a per-user KERNEL vault. The same boundary applies to 1Password, Doppler, HashiCorp Vault, or another provider: only trusted backend code reads and writes the values.
+
+
+
+```typescript TypeScript
+import Kernel from "@onkernel/sdk";
+import {
+ GetSecretValueCommand,
+ SecretsManagerClient,
+} from "@aws-sdk/client-secrets-manager";
+
+const secrets = new SecretsManagerClient({ region: "us-east-1" });
+const source = await secrets.send(
+ new GetSecretValueCommand({ SecretId: "production/account-portal" }),
+);
+if (!source.SecretString) {
+ throw new Error("account portal credential is unavailable");
+}
+
+const credential = JSON.parse(source.SecretString) as Record;
+if (
+ typeof credential.username !== "string" ||
+ typeof credential.password !== "string" ||
+ !credential.username ||
+ !credential.password
+) {
+ throw new Error("account portal credential is incomplete");
+}
+
+const kernel = new Kernel({ projectID: process.env.KERNEL_PROJECT_ID });
+const vault = await kernel.vaults.upsert({ name: "user-12345" });
+const item = await kernel.vaults.items.upsert("portal-login", {
+ id_or_name: vault.id,
+ type: "credential",
+ spec: {
+ description: "Account Portal",
+ fields: {
+ username: {
+ type: "email",
+ required: true,
+ sensitive: true,
+ value: credential.username,
+ },
+ password: {
+ type: "password",
+ required: true,
+ sensitive: true,
+ value: credential.password,
+ },
+ },
+ },
+});
+if (item.type !== "credential" || item.state.status !== "ready") {
+ throw new Error("credential is not ready");
+}
+```
+
+```python Python
+import json
+import os
+
+import boto3
+from kernel import Kernel
+
+secrets = boto3.client("secretsmanager", region_name="us-east-1")
+source = secrets.get_secret_value(SecretId="production/account-portal")
+credential = json.loads(source["SecretString"])
+if (
+ not isinstance(credential.get("username"), str)
+ or not isinstance(credential.get("password"), str)
+ or not credential["username"]
+ or not credential["password"]
+):
+ raise RuntimeError("account portal credential is incomplete")
+
+kernel = Kernel(project_id=os.environ["KERNEL_PROJECT_ID"])
+vault = kernel.vaults.upsert(name="user-12345")
+item = kernel.vaults.items.upsert(
+ "portal-login",
+ id_or_name=vault.id,
+ type="credential",
+ spec={
+ "description": "Account Portal",
+ "fields": {
+ "username": {
+ "type": "email",
+ "required": True,
+ "sensitive": True,
+ "value": credential["username"],
+ },
+ "password": {
+ "type": "password",
+ "required": True,
+ "sensitive": True,
+ "value": credential["password"],
+ },
+ },
+ },
+)
+if item.type != "credential" or item.state.status != "ready":
+ raise RuntimeError("credential is not ready")
+```
+
+
+
+`upsert` creates the item the first time. Repeating it retrieves the existing item without overwriting later values. Use an authenticated item update for rotations.
+
+## Synchronize rotations
+
+run synchronization from your backend after the source vault rotates, or immediately before a workflow that requires a fresh value. Retrieve the KERNEL item, verify its immutable id, and update only the changed fields with its latest `version`. A successful update invalidates outstanding hosted collection sessions.
+
+If an update returns `409`, retrieve the item again and reconcile the newer version. Don't automatically resubmit a stale value. See [read and update values](/vaults/credentials#read-and-update-values) for TypeScript and Python examples.
+
+KERNEL doesn't poll the source vault. If the source is unavailable, don't replace the KERNEL item with empty or partial values. Decide whether your policy permits the last copied value to remain usable before starting the browser workflow.
+
+## Coordinate deletion
+
+deleting or revoking the source credential doesn't delete its KERNEL copy. Delete the KERNEL credential item when:
+
+- the source credential is deleted or access is revoked.
+- the end user disconnects the source vault.
+- the workflow no longer needs the credential.
+- your retention policy no longer permits KERNEL to store the copy.
+
+Keep the source credential's immutable identifier alongside the KERNEL vault and item ids in your backend. Use that mapping for authorization, rotation, and deletion without putting credential values in application logs or metadata.
+
+## Compare with Managed Auth and 1Password
+
+KERNEL's [1Password integration](/integrations/1password) is specific to Managed Auth. Managed Auth retrieves matching values from 1Password when it authenticates and doesn't store them in KERNEL.
+
+Vaults + Credential Fill uses a different boundary:
+
+| | Existing vault + Credential Fill | Managed Auth + 1Password |
+| --- | --- | --- |
+| **who reads the source** | your trusted backend | Managed Auth |
+| **storage in KERNEL** | encrypted credential copy | values remain in 1Password |
+| **synchronization** | your backend updates or deletes the copy | Managed Auth retrieves values at authentication time |
+| **login control** | your application or agent | Managed Auth |
+
+## Security checklist
+
+- keep source-vault credentials and KERNEL api keys in trusted backend code.
+- authorize the mapping between the end user, source secret, KERNEL vault, and credential item.
+- keep password, totp, and other secrets marked `sensitive: true`.
+- don't put values in agent prompts, frontend code, command-line arguments, logs, traces, or metadata.
+- attach a vault only to browser sessions authorized to use all of its items.
+- treat values as exposed to the browser after fill; page scripts, extensions, developer tools, or an unrestricted agent can read them.
+
+## Next steps
+
+
+
+ define fields and update copied values without returning sensitive fields.
+
+
+ attach the vault, map fields to selectors, and handle the fill outcome.
+
+
diff --git a/docs.json b/docs.json
index de2ea7ad..4b20d3ee 100644
--- a/docs.json
+++ b/docs.json
@@ -119,7 +119,8 @@
{
"group": "Vaults + Credential Fill",
"pages": [
- "auth/credential-fill"
+ "auth/credential-fill",
+ "auth/credential-fill/existing-vault"
]
},
{
diff --git a/vaults/credentials.mdx b/vaults/credentials.mdx
index 44e896fd..a2937057 100644
--- a/vaults/credentials.mdx
+++ b/vaults/credentials.mdx
@@ -85,6 +85,8 @@ if your application already stores a username and password in another vault,
read them from your trusted backend and include each `value` in the initial
`upsert`. this creates a ready item without opening a collection form. the
example uses aws secrets manager, but the same flow applies to another vault.
+see [use an existing credential vault](/auth/credential-fill/existing-vault) for
+the complete synchronization, deletion, and security model.
today, this operation copies the values into KERNEL rather than creating a live
connection to the source vault. KERNEL encrypts and stores the copy. your
From f6c33e393006938812417254a06173599daf9cb3 Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Wed, 16 Sep 2026 00:03:59 +0000
Subject: [PATCH 06/27] Clarify credential fill and vault ownership
---
auth/credential-fill.mdx | 4 ++--
docs.json | 11 ++++++++---
vaults/credentials.mdx | 2 +-
.../existing-credential-vault.mdx | 2 +-
vaults/fill.mdx | 4 ++--
vaults/overview.mdx | 11 +++++++----
6 files changed, 21 insertions(+), 13 deletions(-)
rename auth/credential-fill/existing-vault.mdx => vaults/existing-credential-vault.mdx (96%)
diff --git a/auth/credential-fill.mdx b/auth/credential-fill.mdx
index 6cd44209..fbf9070e 100644
--- a/auth/credential-fill.mdx
+++ b/auth/credential-fill.mdx
@@ -3,7 +3,7 @@ title: "Overview"
description: "Collect end-user credentials and inject them into browser forms while controlling the login workflow"
---
-Vaults + Credential Fill gives your application or agent direct control over authentication. Use it when an end user supplies credentials during a task and your workflow needs to own navigation, submission, and recovery.
+Vaults + Credential Fill gives your application or agent direct control over authentication when an end user supplies credentials during a task. use KERNEL fill instead of injecting values directly so your controller sends field names and selectors rather than credential values. KERNEL reads the encrypted item, writes the selected values into the browser, and returns value-free outcomes. this keeps credentials out of agent prompts and browser-automation payloads while your workflow retains control of navigation, submission, and recovery.
start with the [end-user auth workflow cookbook](/browsers/use-vault-credentials-in-browser-agent) for an end-to-end example of secure collection, browser attachment, credential fill, form submission, and cleanup.
@@ -47,7 +47,7 @@ Choose [Managed Auth](/auth/managed-auth) instead when you want KERNEL to run th
## Credential sources
-you can collect values from an end user with KERNEL's hosted collection form or [copy them from an existing credential vault](/auth/credential-fill/existing-vault) that your trusted backend can read. Both paths create the same ready credential item and use the same fill operation.
+you can collect values from an end user with KERNEL's hosted collection form or [copy them from an existing credential vault](/vaults/existing-credential-vault) that your trusted backend can read. Both paths create the same ready credential item and use the same fill operation.
Today, copying values stores an encrypted KERNEL copy. Credential Fill doesn't accept raw values or a third-party vault reference in the fill request.
diff --git a/docs.json b/docs.json
index 4b20d3ee..becd86d3 100644
--- a/docs.json
+++ b/docs.json
@@ -10,6 +10,7 @@
{ "source": "/auth/agent/hosted-ui", "destination": "/auth/hosted-ui" },
{ "source": "/auth/agent/programmatic", "destination": "/auth/programmatic" },
{ "source": "/auth/agent/faq", "destination": "/auth/faq" },
+ { "source": "/auth/credential-fill/existing-vault", "destination": "/vaults/existing-credential-vault" },
{ "source": "/browsers/hardware-acceleration", "destination": "/browsers/gpu-acceleration" },
{ "source": "/integrations/computer-use", "destination": "/integrations/computer-use/overview" },
{ "source": "/integrations/claude", "destination": "/integrations/claude/overview" },
@@ -119,8 +120,7 @@
{
"group": "Vaults + Credential Fill",
"pages": [
- "auth/credential-fill",
- "auth/credential-fill/existing-vault"
+ "auth/credential-fill"
]
},
{
@@ -141,7 +141,12 @@
},
{
"group": "Vaults",
- "pages": ["vaults/overview", "vaults/credentials", "vaults/fill"]
+ "pages": [
+ "vaults/overview",
+ "vaults/credentials",
+ "vaults/existing-credential-vault",
+ "vaults/fill"
+ ]
},
"config-registry",
"info/api-keys",
diff --git a/vaults/credentials.mdx b/vaults/credentials.mdx
index a2937057..85b2c7b7 100644
--- a/vaults/credentials.mdx
+++ b/vaults/credentials.mdx
@@ -85,7 +85,7 @@ if your application already stores a username and password in another vault,
read them from your trusted backend and include each `value` in the initial
`upsert`. this creates a ready item without opening a collection form. the
example uses aws secrets manager, but the same flow applies to another vault.
-see [use an existing credential vault](/auth/credential-fill/existing-vault) for
+see [use an existing credential vault](/vaults/existing-credential-vault) for
the complete synchronization, deletion, and security model.
today, this operation copies the values into KERNEL rather than creating a live
diff --git a/auth/credential-fill/existing-vault.mdx b/vaults/existing-credential-vault.mdx
similarity index 96%
rename from auth/credential-fill/existing-vault.mdx
rename to vaults/existing-credential-vault.mdx
index ed1afee9..a521088f 100644
--- a/auth/credential-fill/existing-vault.mdx
+++ b/vaults/existing-credential-vault.mdx
@@ -3,7 +3,7 @@ title: "Use an Existing Credential Vault"
description: "Copy credentials from an existing vault into KERNEL for browser fill"
---
-keep an existing credential vault as your source of truth while using KERNEL to fill browser forms. Your trusted backend reads the source credential, copies it into a KERNEL credential item, and updates or deletes that copy as the source changes.
+keep an existing credential vault as your source of truth while using KERNEL to fill browser forms. this is the credential-source setup for [Vaults + Credential Fill](/auth/credential-fill): your trusted backend reads the source credential, copies it into a KERNEL credential item, and updates or deletes that copy as the source changes.
Credential Fill doesn't currently read directly from a third-party vault or accept a provider reference in a fill request. KERNEL stores an encrypted copy of the values. Your backend is responsible for synchronization and deletion.
diff --git a/vaults/fill.mdx b/vaults/fill.mdx
index bc0d3f13..e8fceef4 100644
--- a/vaults/fill.mdx
+++ b/vaults/fill.mdx
@@ -7,8 +7,8 @@ invoke an item's `fill` operation to write selected values into an attached brow
`fill` reads credentials from a ready KERNEL credential item. if another vault
- is your source of truth, [copy its values into the credential
- item](/vaults/credentials#copy-values-from-an-existing-vault) first. today,
+ is your source of truth, [copy its values into a KERNEL credential
+ item](/vaults/existing-credential-vault) first. today,
this stores an encrypted copy in KERNEL; `fill` doesn't accept credential
values or a third-party vault reference in its request.
diff --git a/vaults/overview.mdx b/vaults/overview.mdx
index 9abf16f8..0ab10456 100644
--- a/vaults/overview.mdx
+++ b/vaults/overview.mdx
@@ -15,6 +15,9 @@ selected browser inputs and returns value-free outcomes. payment aliases are
non-sensitive stand-ins that KERNEL resolves at egress, outside the browser.
choose the path deliberately: their exposure boundaries differ.
+for authentication workflows where your application or agent controls
+navigation and submission, start with [Vaults + Credential Fill](/auth/credential-fill).
+
fill isn't secret isolation from the browser. an agent with unrestricted
browser access, page scripts, or extensions can read values after filling.
@@ -48,10 +51,9 @@ a hosted flow, without passing card data through your application or agent.
you can keep your existing vault as the source of truth. today, your trusted
backend reads the values from that vault and [copies them into a KERNEL credential
-item](/vaults/credentials#copy-values-from-an-existing-vault). KERNEL encrypts and
-stores that copy. the credential item becomes ready, and `fill` can write its
-fields into an attached browser without including their values in the fill
-request.
+item](/vaults/existing-credential-vault). KERNEL encrypts and stores that copy.
+the credential item becomes ready, and `fill` can write its fields into an
+attached browser without including their values in the fill request.
the copy isn't a live connection to your existing vault. when a credential
changes there, update the KERNEL item before its next use. delete the item when
@@ -305,6 +307,7 @@ card state can include `masks.brand`, `masks.last4`, and read-only aliases: `num
## Next steps
- [credential items](/vaults/credentials): define fields, collect values, and update them safely.
+- [use an existing credential vault](/vaults/existing-credential-vault): copy credentials from another vault and synchronize their lifecycle.
- [fill browser fields](/vaults/fill): map credential fields to browser inputs and handle outcomes.
- [human-in-the-loop credential collection and form filling](/browsers/use-vault-credentials-in-browser-agent): try a cli prompt, then follow the sdk and cli walkthrough.
- [enable payments in a browser agent](/browsers/enable-payments-in-browser-agent): connect a wallet and complete an alias-based checkout.
From 1e5698446803cc3ed42d30b26b8ffcff11af8804 Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Wed, 16 Sep 2026 01:02:57 +0000
Subject: [PATCH 07/27] Clarify auth use cases and lifecycle boundaries
---
auth/credential-fill.mdx | 5 ++
auth/managed-auth.mdx | 9 +++
auth/overview.mdx | 8 ++
vaults/existing-credential-vault.mdx | 111 +--------------------------
4 files changed, 24 insertions(+), 109 deletions(-)
diff --git a/auth/credential-fill.mdx b/auth/credential-fill.mdx
index fbf9070e..323f863a 100644
--- a/auth/credential-fill.mdx
+++ b/auth/credential-fill.mdx
@@ -9,6 +9,10 @@ start with the [end-user auth workflow cookbook](/browsers/use-vault-credentials
KERNEL collects credential values or accepts them from a trusted backend, encrypts them in a credential item, and fills selected browser fields without including the values in the fill request or response. Your application or agent decides where to navigate, which fields to fill, when to submit, and how to handle the site's response.
+
+ Credential Fill only writes stored values into fields you select. it doesn't discover fields, navigate, submit forms, verify authentication, monitor the session, or reauthenticate. your application or agent owns each of those steps.
+
+
fill writes real values into the browser. Page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them after filling.
@@ -17,6 +21,7 @@ KERNEL collects credential values or accepts them from a trusted backend, encryp
Vaults + Credential Fill works best when:
+- you're building an ai assistant that asks users to sign in during a task, such as downloading an invoice from their account, while retaining control of the browser workflow.
- an end user owns the credentials and remains present during the task.
- a login or authentication prompt can appear in the middle of a workflow.
- your product needs to control the credential collection experience.
diff --git a/auth/managed-auth.mdx b/auth/managed-auth.mdx
index 062bb6cd..e3d15eac 100644
--- a/auth/managed-auth.mdx
+++ b/auth/managed-auth.mdx
@@ -7,6 +7,15 @@ Managed Auth creates and maintains authenticated browser sessions for your AI ag
Managed Auth works best when you want KERNEL to control the login flow and maintain the resulting session. If your end user supplies credentials while a task is running and your application or agent needs to control navigation and submission, use [Vaults + Credential Fill](/auth/credential-fill).
+
+ when a health check detects a logged-out session, KERNEL automatically attempts to reauthenticate if the connection is eligible (`can_reauth: true`). reauthentication isn't guaranteed: missing credentials, required human input, or repeated login failures can leave the connection in `NEEDS_AUTH`. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery.
+
+
+## When to use it
+
+- **website qa:** reuse signed-in sessions to test account pages without building a login flow into every test.
+- **automations on known sites:** run recurring tasks, such as retrieving reports, across a core set of account portals with reusable Managed Auth connections.
+
## How it works
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 1f6966c6..50ab7d85 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -23,6 +23,7 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
| | Vaults + Credential Fill | Managed Auth |
| --- | --- | --- |
| **best for** | user-present workflows where an end user supplies credentials during a task | developer- or organization-controlled credentials in repeatable or unattended automations |
+| **example use cases** | ai assistants that ask users to sign in during a task | website qa and recurring automations on a core set of known sites |
| **login navigation** | your application or agent | KERNEL |
| **credential collection** | KERNEL-hosted collection form or your trusted backend | Managed Auth credential, Hosted UI, React component, or programmatic flow |
| **form filling and submission** | KERNEL fills the selected fields; your application or agent submits the form | KERNEL |
@@ -38,6 +39,7 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
### Use Vaults + Credential Fill
+- ai assistants that encounter a login during a user-directed task, such as downloading an invoice from the user's account. the assistant controls navigation and asks the user for credentials when needed.
- your end user owns the credentials and is present during the task.
- an authentication prompt can appear in the middle of a longer workflow.
- your product needs to control when and how it asks for credentials.
@@ -45,11 +47,17 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
### Use Managed Auth
+- website qa that needs signed-in sessions to test account pages without building a login flow into every test.
+- recurring automations on a core set of known sites, such as retrieving reports from the same account portals each day.
- your automation uses developer- or organization-controlled credentials.
- the automation runs unattended or signs in repeatedly.
- you want KERNEL to navigate common login, sso, and mfa flows.
- you want health checks and eligible automatic reauthentication.
+
+ when Managed Auth detects a logged-out session during a health check, KERNEL automatically attempts to reauthenticate if the connection is eligible (`can_reauth: true`). this is an attempt, not a guarantee of success. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery when human input is required.
+
+
## Understand the security boundary
KERNEL doesn't return stored sensitive fields in api responses or add them to model context. Credential Fill writes real values into the browser. Page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them after fill. Use the narrowest browser permissions that your workflow supports, and only attach a vault to sessions authorized to use all of its items.
diff --git a/vaults/existing-credential-vault.mdx b/vaults/existing-credential-vault.mdx
index a521088f..843138dd 100644
--- a/vaults/existing-credential-vault.mdx
+++ b/vaults/existing-credential-vault.mdx
@@ -28,118 +28,11 @@ keep an existing credential vault as your source of truth while using KERNEL to
## Copy a credential
-the following example reads an account credential from aws secrets manager, validates it, and copies it into a per-user KERNEL vault. The same boundary applies to 1Password, Doppler, HashiCorp Vault, or another provider: only trusted backend code reads and writes the values.
-
-
-
-```typescript TypeScript
-import Kernel from "@onkernel/sdk";
-import {
- GetSecretValueCommand,
- SecretsManagerClient,
-} from "@aws-sdk/client-secrets-manager";
-
-const secrets = new SecretsManagerClient({ region: "us-east-1" });
-const source = await secrets.send(
- new GetSecretValueCommand({ SecretId: "production/account-portal" }),
-);
-if (!source.SecretString) {
- throw new Error("account portal credential is unavailable");
-}
-
-const credential = JSON.parse(source.SecretString) as Record;
-if (
- typeof credential.username !== "string" ||
- typeof credential.password !== "string" ||
- !credential.username ||
- !credential.password
-) {
- throw new Error("account portal credential is incomplete");
-}
-
-const kernel = new Kernel({ projectID: process.env.KERNEL_PROJECT_ID });
-const vault = await kernel.vaults.upsert({ name: "user-12345" });
-const item = await kernel.vaults.items.upsert("portal-login", {
- id_or_name: vault.id,
- type: "credential",
- spec: {
- description: "Account Portal",
- fields: {
- username: {
- type: "email",
- required: true,
- sensitive: true,
- value: credential.username,
- },
- password: {
- type: "password",
- required: true,
- sensitive: true,
- value: credential.password,
- },
- },
- },
-});
-if (item.type !== "credential" || item.state.status !== "ready") {
- throw new Error("credential is not ready");
-}
-```
-
-```python Python
-import json
-import os
-
-import boto3
-from kernel import Kernel
-
-secrets = boto3.client("secretsmanager", region_name="us-east-1")
-source = secrets.get_secret_value(SecretId="production/account-portal")
-credential = json.loads(source["SecretString"])
-if (
- not isinstance(credential.get("username"), str)
- or not isinstance(credential.get("password"), str)
- or not credential["username"]
- or not credential["password"]
-):
- raise RuntimeError("account portal credential is incomplete")
-
-kernel = Kernel(project_id=os.environ["KERNEL_PROJECT_ID"])
-vault = kernel.vaults.upsert(name="user-12345")
-item = kernel.vaults.items.upsert(
- "portal-login",
- id_or_name=vault.id,
- type="credential",
- spec={
- "description": "Account Portal",
- "fields": {
- "username": {
- "type": "email",
- "required": True,
- "sensitive": True,
- "value": credential["username"],
- },
- "password": {
- "type": "password",
- "required": True,
- "sensitive": True,
- "value": credential["password"],
- },
- },
- },
-)
-if item.type != "credential" or item.state.status != "ready":
- raise RuntimeError("credential is not ready")
-```
-
-
-
-`upsert` creates the item the first time. Repeating it retrieves the existing item without overwriting later values. Use an authenticated item update for rotations.
+use the canonical [copy values from an existing vault](/vaults/credentials#copy-values-from-an-existing-vault) example for TypeScript and Python. it reads an account credential from aws secrets manager, validates it, and copies it into a KERNEL credential item. the same trusted-backend boundary applies to other providers.
## Synchronize rotations
-run synchronization from your backend after the source vault rotates, or immediately before a workflow that requires a fresh value. Retrieve the KERNEL item, verify its immutable id, and update only the changed fields with its latest `version`. A successful update invalidates outstanding hosted collection sessions.
-
-If an update returns `409`, retrieve the item again and reconcile the newer version. Don't automatically resubmit a stale value. See [read and update values](/vaults/credentials#read-and-update-values) for TypeScript and Python examples.
+run synchronization from your backend after the source vault rotates, or immediately before a workflow that requires a fresh value. follow [read and update values](/vaults/credentials#read-and-update-values) for the canonical TypeScript and Python examples, immutable item identity checks, version preconditions, collection-session invalidation, and conflict handling.
KERNEL doesn't poll the source vault. If the source is unavailable, don't replace the KERNEL item with empty or partial values. Decide whether your policy permits the last copied value to remain usable before starting the browser workflow.
From 2fa9c567e40c5a775e96db674ad887da0eb37e44 Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Wed, 16 Sep 2026 01:11:53 +0000
Subject: [PATCH 08/27] Trim auth use cases and revise Managed Auth card
---
auth/managed-auth.mdx | 5 -----
auth/overview.mdx | 5 +----
2 files changed, 1 insertion(+), 9 deletions(-)
diff --git a/auth/managed-auth.mdx b/auth/managed-auth.mdx
index e3d15eac..73e5fa50 100644
--- a/auth/managed-auth.mdx
+++ b/auth/managed-auth.mdx
@@ -11,11 +11,6 @@ Managed Auth works best when you want KERNEL to control the login flow and maint
when a health check detects a logged-out session, KERNEL automatically attempts to reauthenticate if the connection is eligible (`can_reauth: true`). reauthentication isn't guaranteed: missing credentials, required human input, or repeated login failures can leave the connection in `NEEDS_AUTH`. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery.
-## When to use it
-
-- **website qa:** reuse signed-in sessions to test account pages without building a login flow into every test.
-- **automations on known sites:** run recurring tasks, such as retrieving reports, across a core set of account portals with reusable Managed Auth connections.
-
## How it works
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 50ab7d85..e009065e 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -16,7 +16,7 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
**delegate the login lifecycle**
- best when your application controls the credentials and you want KERNEL to navigate common login, sso, and mfa steps, save the authenticated state, and monitor the connection.
+ best when your application controls the credentials and you want KERNEL to handle the login, sso, and mfa steps, save the authenticated state, and attempt to re-auth automatically.
@@ -39,7 +39,6 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
### Use Vaults + Credential Fill
-- ai assistants that encounter a login during a user-directed task, such as downloading an invoice from the user's account. the assistant controls navigation and asks the user for credentials when needed.
- your end user owns the credentials and is present during the task.
- an authentication prompt can appear in the middle of a longer workflow.
- your product needs to control when and how it asks for credentials.
@@ -47,8 +46,6 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
### Use Managed Auth
-- website qa that needs signed-in sessions to test account pages without building a login flow into every test.
-- recurring automations on a core set of known sites, such as retrieving reports from the same account portals each day.
- your automation uses developer- or organization-controlled credentials.
- the automation runs unattended or signs in repeatedly.
- you want KERNEL to navigate common login, sso, and mfa flows.
From 288a04313d9c243e1c1c136c1633ac3137ded246 Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Wed, 16 Sep 2026 01:13:37 +0000
Subject: [PATCH 09/27] Compare where each auth path runs login
---
auth/overview.mdx | 1 +
1 file changed, 1 insertion(+)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index e009065e..9b8ccc4d 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -23,6 +23,7 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
| | Vaults + Credential Fill | Managed Auth |
| --- | --- | --- |
| **best for** | user-present workflows where an end user supplies credentials during a task | developer- or organization-controlled credentials in repeatable or unattended automations |
+| **where login happens** | in your agent’s current browser session | in a separate browser session managed by KERNEL |
| **example use cases** | ai assistants that ask users to sign in during a task | website qa and recurring automations on a core set of known sites |
| **login navigation** | your application or agent | KERNEL |
| **credential collection** | KERNEL-hosted collection form or your trusted backend | Managed Auth credential, Hosted UI, React component, or programmatic flow |
From fb23fd90616cfbf2a495a533dc2cf34034aa1237 Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 18:18:34 -0700
Subject: [PATCH 10/27] Apply suggestion from @AnnaXWang
---
auth/overview.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 9b8ccc4d..3a7f7dcf 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -22,7 +22,7 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
| | Vaults + Credential Fill | Managed Auth |
| --- | --- | --- |
-| **best for** | user-present workflows where an end user supplies credentials during a task | developer- or organization-controlled credentials in repeatable or unattended automations |
+| **best for** | agents doing work on behalf of an end user | recurring automations using developer- or organization-controlled credentials |
| **where login happens** | in your agent’s current browser session | in a separate browser session managed by KERNEL |
| **example use cases** | ai assistants that ask users to sign in during a task | website qa and recurring automations on a core set of known sites |
| **login navigation** | your application or agent | KERNEL |
From 4915b498b21617dc947a7cd169e070697b49b67a Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 18:19:34 -0700
Subject: [PATCH 11/27] Apply suggestion from @AnnaXWang
---
auth/overview.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 3a7f7dcf..a04d0a61 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -24,7 +24,7 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
| --- | --- | --- |
| **best for** | agents doing work on behalf of an end user | recurring automations using developer- or organization-controlled credentials |
| **where login happens** | in your agent’s current browser session | in a separate browser session managed by KERNEL |
-| **example use cases** | ai assistants that ask users to sign in during a task | website qa and recurring automations on a core set of known sites |
+| **example use cases** | ai assistants that ask users to sign in during a task | website qa on a core set of known sites |
| **login navigation** | your application or agent | KERNEL |
| **credential collection** | KERNEL-hosted collection form or your trusted backend | Managed Auth credential, Hosted UI, React component, or programmatic flow |
| **form filling and submission** | KERNEL fills the selected fields; your application or agent submits the form | KERNEL |
From 640b93a6a5270b7c1ec9a9db49c9253426434f37 Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 18:21:25 -0700
Subject: [PATCH 12/27] Update auth/overview.mdx
---
auth/overview.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index a04d0a61..3fada5e4 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -11,7 +11,7 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
**control the login workflow**
- best when an end user owns the credentials. collect them during a task, then have your application or agent navigate, fill, submit, and handle the site's response.
+ best when an end user owns the credentials and you want to own the orchestration. collect credentials before or during a task, then have your application or agent navigate, fill, submit, and handle the site's response.
**delegate the login lifecycle**
From 07c8620c6fc9500ca96702bb31580ce7024b8c29 Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 18:34:37 -0700
Subject: [PATCH 13/27] Apply suggestion from @AnnaXWang
---
auth/overview.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 3fada5e4..0d33043a 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -3,7 +3,7 @@ title: "Overview"
description: "Choose how your browser agents authenticate and reuse signed-in sessions"
---
-most useful browser workflows begin behind a login. KERNEL gives you two ways to authenticate browser agents without returning stored sensitive values through the api or putting them in your agent prompt: delegate the login and session lifecycle to Managed Auth, or control the workflow yourself with Vaults + Credential Fill.
+most useful browser workflows begin behind a login. KERNEL gives you two ways to authenticate browser agents without returning stored sensitive values through the api or putting them in your agent prompt: control the workflow yourself with Vaults + Credential Fill, or delegate the login and session lifecycle to Managed Auth.
## Choose an auth approach
From d61092cf640be81e7e442414816a3fcd58244a59 Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 18:42:21 -0700
Subject: [PATCH 14/27] Apply batched suggestions from code review
Co-authored-by: Anna Wang
---
auth/overview.mdx | 2 --
1 file changed, 2 deletions(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 0d33043a..c9bd7c07 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -11,12 +11,10 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
**control the login workflow**
- best when an end user owns the credentials and you want to own the orchestration. collect credentials before or during a task, then have your application or agent navigate, fill, submit, and handle the site's response.
**delegate the login lifecycle**
- best when your application controls the credentials and you want KERNEL to handle the login, sso, and mfa steps, save the authenticated state, and attempt to re-auth automatically.
From 3cd27328e7d4d65efc947c022c0014c2795700f9 Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 18:43:40 -0700
Subject: [PATCH 15/27] Apply suggestion from @AnnaXWang
---
auth/overview.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index c9bd7c07..19d80660 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -20,7 +20,7 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
| | Vaults + Credential Fill | Managed Auth |
| --- | --- | --- |
-| **best for** | agents doing work on behalf of an end user | recurring automations using developer- or organization-controlled credentials |
+| **best for** | agents doing work on behalf of an end user, using the end user's credentials | recurring automations using developer- or organization-controlled credentials |
| **where login happens** | in your agent’s current browser session | in a separate browser session managed by KERNEL |
| **example use cases** | ai assistants that ask users to sign in during a task | website qa on a core set of known sites |
| **login navigation** | your application or agent | KERNEL |
From ff9f926f1f5608ef6217882f90dfcdc862f094af Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 18:54:00 -0700
Subject: [PATCH 16/27] Apply suggestion from @AnnaXWang
---
auth/overview.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 19d80660..8214225b 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -69,6 +69,6 @@ KERNEL doesn't return stored sensitive fields in api responses or add them to mo
collect end-user credentials and control navigation, form submission, and recovery in your own workflow.
- let KERNEL run the login flow and maintain the authenticated session.
+ let KERNEL run the login flow automatically attempt re-authentication.```
From 46edc53c4c7b747ba021e1feb3d2e11734575821 Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 18:59:57 -0700
Subject: [PATCH 17/27] Apply batched suggestions from code review
Co-authored-by: Anna Wang
---
auth/overview.mdx | 6 ++----
1 file changed, 2 insertions(+), 4 deletions(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 8214225b..e66cd12f 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -38,14 +38,12 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
### Use Vaults + Credential Fill
-- your end user owns the credentials and is present during the task.
-- an authentication prompt can appear in the middle of a longer workflow.
+- an authentication prompt can appear in the middle of a longer workflow, in the same browser session.
- your product needs to control when and how it asks for credentials.
- your application or agent must own navigation, submission, and recovery.
### Use Managed Auth
-- your automation uses developer- or organization-controlled credentials.
- the automation runs unattended or signs in repeatedly.
- you want KERNEL to navigate common login, sso, and mfa flows.
- you want health checks and eligible automatic reauthentication.
@@ -69,6 +67,6 @@ KERNEL doesn't return stored sensitive fields in api responses or add them to mo
collect end-user credentials and control navigation, form submission, and recovery in your own workflow.
- let KERNEL run the login flow automatically attempt re-authentication.```
+ let KERNEL run the login flow and automatically attempt re-authentication.
From 394d2748a5a4c2bb9c532fbb5893b3801238601c Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 19:04:04 -0700
Subject: [PATCH 18/27] Apply suggestion from @AnnaXWang
---
auth/overview.mdx | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index e66cd12f..27a77e00 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -20,10 +20,9 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
| | Vaults + Credential Fill | Managed Auth |
| --- | --- | --- |
-| **best for** | agents doing work on behalf of an end user, using the end user's credentials | recurring automations using developer- or organization-controlled credentials |
-| **where login happens** | in your agent’s current browser session | in a separate browser session managed by KERNEL |
-| **example use cases** | ai assistants that ask users to sign in during a task | website qa on a core set of known sites |
| **login navigation** | your application or agent | KERNEL |
+| **where login happens** | in your agent’s current browser session | in a separate browser session managed by KERNEL |
+| **example use cases** | agents that do work on behalf of an end user, using the end user's credentials | recurring website qa on a set of known sites |
| **credential collection** | KERNEL-hosted collection form or your trusted backend | Managed Auth credential, Hosted UI, React component, or programmatic flow |
| **form filling and submission** | KERNEL fills the selected fields; your application or agent submits the form | KERNEL |
| **site response handling** | your application or agent | KERNEL |
From cfff4f7a07433c5ddf4fab0f1f3100809867c24b Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Wed, 16 Sep 2026 02:04:37 +0000
Subject: [PATCH 19/27] Clarify automatic reauthentication limits and
interactive recovery
---
auth/configuration.mdx | 8 ++++----
auth/connection-lifecycle.mdx | 2 +-
auth/credentials.mdx | 4 ++--
auth/faq.mdx | 8 ++++++--
auth/hosted-ui.mdx | 2 +-
auth/managed-auth.mdx | 16 ++++++++--------
auth/programmatic.mdx | 2 +-
auth/react.mdx | 6 ++++++
integrations/1password.mdx | 2 +-
9 files changed, 30 insertions(+), 20 deletions(-)
diff --git a/auth/configuration.mdx b/auth/configuration.mdx
index 4f849955..2ce788d9 100644
--- a/auth/configuration.mdx
+++ b/auth/configuration.mdx
@@ -8,16 +8,16 @@ Managed Auth connections use the same configuration whether you collect credenti
## Credentials and Auto-Reauth
-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.
+by default, KERNEL saves durable credential fields after a successful login. these can support eligible automatic reauthentication attempts, including totp codes generated from an available secret. submitted one-time codes aren't saved and don't provide access to future codes. if a later login requires user input, your application must start a new interactive login.
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`:
- `health_checks` — whether the connection runs periodic health checks at all. When `false`, the system never automatically verifies the session and never triggers reauth on its own.
-- `auto_reauth` — whether a failed scheduled health check is allowed to attempt re-authentication. When `false`, expired sessions are marked `NEEDS_AUTH` instead of being repaired automatically.
+- `auto_reauth` — whether a scheduled health check that confirms the session is logged out may trigger an eligible automatic reauthentication attempt. when `false`, expired sessions are marked `NEEDS_AUTH` without an automatic recovery attempt.
-`auto_reauth` only has an effect on the automatic flow when `health_checks` is also `true`, because reauth is triggered by a failing scheduled health check. Manually triggering a health check via the API still works regardless of `health_checks`.
+`auto_reauth` only has an effect on the automatic flow when `health_checks` is also `true`, because reauthentication requires a scheduled health check to confirm the session is logged out. an inconclusive check doesn't trigger reauthentication. manually triggering a health check via the api still works regardless of `health_checks`.
```typescript TypeScript
@@ -443,7 +443,7 @@ After creating a connection, you can update its configuration with `auth.connect
| `allowed_domains` | Update allowed redirect domains |
| `health_check_interval` | Seconds between health checks (minimum varies by plan) |
| `health_checks` | Whether periodic health checks run for this connection |
-| `auto_reauth` | Whether a failed scheduled health check is allowed to attempt automatic re-authentication |
+| `auto_reauth` | Whether a scheduled health check that confirms a logged-out session may trigger an eligible automatic reauthentication attempt |
| `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) |
| `browser.region` | Region for login, health-check, and reauth browsers. Takes effect on the next browser created for the connection |
diff --git a/auth/connection-lifecycle.mdx b/auth/connection-lifecycle.mdx
index b26af6e6..efddede2 100644
--- a/auth/connection-lifecycle.mdx
+++ b/auth/connection-lifecycle.mdx
@@ -88,7 +88,7 @@ After a successful login, Kernel saves the login flow. If a later attempt needs
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.
+- **Switch to TOTP** — if the site supports authenticator apps, add a `totp_secret` to your credential. KERNEL generates codes on demand, removing the need to manually provide that authenticator code. this doesn't eliminate other challenges or guarantee unattended reauthentication. 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.
## Triggering re-auth manually
diff --git a/auth/credentials.mdx b/auth/credentials.mdx
index 2dae233d..997b4264 100644
--- a/auth/credentials.mdx
+++ b/auth/credentials.mdx
@@ -1,9 +1,9 @@
---
title: "Managed Auth Credentials"
-description: "Use stored credentials for login and automatic reauthentication"
+description: "Use stored credentials for login and eligible automatic reauthentication attempts"
---
-Credentials let you store login information securely. Kernel can automatically authenticate credential-only flows and attempts to provide TOTP codes when needed.
+credentials let you store login information securely. KERNEL can attempt automatic reauthentication for eligible flows using stored credentials, including totp codes generated from an available secret. saving credentials or completing an interactive login doesn't guarantee unattended reauthentication. supplying a one-time code doesn't give KERNEL the ability to obtain future codes. if a site requires user input, start a new [interactive login](/auth/connection-lifecycle#flows-that-need-input-a-choice-or-approval).
**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)
diff --git a/auth/faq.mdx b/auth/faq.mdx
index ee769780..529d9a8b 100644
--- a/auth/faq.mdx
+++ b/auth/faq.mdx
@@ -4,7 +4,11 @@ title: FAQ
## How does automatic re-authentication work?
-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.
+with health checks and automatic reauthentication enabled, KERNEL attempts reauthentication when a scheduled health check confirms that an eligible connection is logged out. `can_reauth: true` means eligible to attempt, not guaranteed to succeed. stored credentials and an available totp secret can support unattended login, but a new code, choice, or approval that requires a user can leave the connection in `NEEDS_AUTH`. your application must start a new interactive login when user input is required. see [connection lifecycle](/auth/connection-lifecycle) for cadence options and eligibility rules.
+
+## Can managed auth automatically handle email or sms verification?
+
+not during unattended reauthentication. if a site requires an email or sms code, your application must start a new interactive login and bring the user back to provide it through the [hosted ui](/auth/hosted-ui), [react component](/auth/react), or [programmatic flow](/auth/programmatic). wait for successful authentication before resuming the automation. a code supplied during an earlier login doesn't give KERNEL access to future codes.
## What are auth choices?
@@ -12,7 +16,7 @@ Auth choices are visible routes a site presents during login, including mfa meth
## Which authentication methods are supported?
-Managed Auth supports common credential, SSO, and multi-step login flows. Automatic reauthentication uses stored credentials and attempts to provide TOTP codes when needed.
+managed auth supports common credential, sso, and multi-step interactive login flows. automatic reauthentication is limited to eligible flows that can complete without human input. KERNEL can generate totp codes from an available secret; email and sms codes, approvals, and other user-required steps need an interactive login.
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.
diff --git a/auth/hosted-ui.mdx b/auth/hosted-ui.mdx
index 6abe6117..1cbc0d7b 100644
--- a/auth/hosted-ui.mdx
+++ b/auth/hosted-ui.mdx
@@ -93,7 +93,7 @@ The user will:
3. Complete 2FA or another verification step if needed
-Kernel can automatically reauthenticate credential-only flows and attempts to provide TOTP codes when needed.
+KERNEL can attempt automatic reauthentication for eligible flows using stored credentials, including totp codes generated from an available secret. completing this interactive login doesn't guarantee unattended reauthentication. supplying an email or sms code doesn't give KERNEL access to future codes. when the connection needs user input again, start a new login and direct the user to its `hosted_url`. see [connection recovery](/auth/connection-lifecycle#flows-that-need-input-a-choice-or-approval).
### 4. Stream until completion
diff --git a/auth/managed-auth.mdx b/auth/managed-auth.mdx
index 73e5fa50..28d3e3f4 100644
--- a/auth/managed-auth.mdx
+++ b/auth/managed-auth.mdx
@@ -1,14 +1,14 @@
---
title: "Overview"
-description: "Maintain authenticated browser sessions for agents"
+description: "Handle website login, reuse session state, and recover eligible connections automatically"
---
-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.
+managed auth handles website login and saves authenticated state to a reusable browser profile for your agents. KERNEL monitors the connection and can attempt automatic reauthentication for eligible flows that can complete without human input. if a site requires an email code, sms code, approval, or another user action, your application must start a new interactive login and bring the user back to complete it before the automation can continue.
-Managed Auth works best when you want KERNEL to control the login flow and maintain the resulting session. If your end user supplies credentials while a task is running and your application or agent needs to control navigation and submission, use [Vaults + Credential Fill](/auth/credential-fill).
+use managed auth when you want KERNEL to orchestrate login and session recovery, and your application can bring the user back when authentication requires their input. use [vaults + credential fill](/auth/credential-fill) when your application or agent needs to control navigation, credential filling, submission, and recovery in its current browser session.
- when a health check detects a logged-out session, KERNEL automatically attempts to reauthenticate if the connection is eligible (`can_reauth: true`). reauthentication isn't guaranteed: missing credentials, required human input, or repeated login failures can leave the connection in `NEEDS_AUTH`. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery.
+ with health checks and automatic reauthentication enabled, KERNEL automatically attempts to reauthenticate when a scheduled health check confirms a logged-out session and the connection is eligible (`can_reauth: true`). eligibility isn't a guarantee of success. if a blocking requirement is already known, an automatic attempt may not run at all. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery.
## How it works
@@ -49,7 +49,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 automatic reauthentication for supported credential-based flows.
+ link a [credential](/auth/credentials) so KERNEL can attempt reauthentication when the connection is eligible. stored credentials alone don't make every flow eligible.
```typescript TypeScript
@@ -170,7 +170,7 @@ if err != nil {
-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.
+these steps establish the initial connection. your integration must also handle `NEEDS_AUTH`: start a new interactive login and bring the user back when a code, choice, or approval is required. wait for successful authentication before resuming work that requires the account. periodic health checks and eligible automatic reauthentication attempts don't replace this recovery path. see [connection lifecycle](/auth/connection-lifecycle) for runtime behavior and configuration options.
## Choose your integration
@@ -201,9 +201,9 @@ The most valuable workflows live behind logins. Managed Auth provides:
- **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
+- **2FA/OTP handling** - KERNEL can generate totp codes when the credential includes a totp secret. email and sms codes, approvals, and other user-required steps need an interactive login
- **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 reauthentication for eligible credential-based flows
+- **Session monitoring** - [Periodic health checks](/auth/connection-lifecycle) and eligible automatic reauthentication attempts
- **Secure by default** - Credentials are encrypted at rest and never exposed in API responses or passed to LLMs
## Security
diff --git a/auth/programmatic.mdx b/auth/programmatic.mdx
index cabeee09..4bcdc8bd 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 reauthentication. During TOTP flows, Kernel attempts to provide the authenticator code automatically.
+a successful interactive login can save durable credentials for eligible automatic reauthentication attempts. KERNEL can generate totp codes when a totp secret is available, but supplying a one-time code doesn't let KERNEL obtain future codes. neither saved credentials nor a successful login guarantees unattended reauthentication. when the connection becomes `NEEDS_AUTH`, start a new login and use the interaction handling below to collect any required user input before resuming the automation.
### 3. Stream and submit
diff --git a/auth/react.mdx b/auth/react.mdx
index 4f433974..6beaee7f 100644
--- a/auth/react.mdx
+++ b/auth/react.mdx
@@ -103,6 +103,12 @@ export default function LoginPage({
The component is client-only — `"use client"` is required in any RSC framework (Next.js App Router, Remix, etc.).
+## Reconnect when user input is required
+
+rendering the component for the initial login doesn't provide ongoing automatic recovery. your application must handle a connection that returns to `NEEDS_AUTH`, such as when the site requires a new email or sms code or an approval.
+
+call `auth.connections.login()` on the existing connection from your backend, then bring the user back to your login route. pass the new login response's `id` as `sessionId` and its fresh `handoff_code` as `handoffCode`. don't reuse the previous handoff code: it is single-use. wait for successful authentication before resuming work that requires the account. see [connection recovery](/auth/connection-lifecycle#flows-that-need-input-a-choice-or-approval).
+
## Backend connectivity
By default the component talks directly to `https://api.onkernel.com`. That works out of the box; nothing else to configure.
diff --git a/integrations/1password.mdx b/integrations/1password.mdx
index ef06c06a..24e0338d 100644
--- a/integrations/1password.mdx
+++ b/integrations/1password.mdx
@@ -142,7 +142,7 @@ If your 1Password item has a one-time password (TOTP) field configured, Kernel c
## Supported Login Types
-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.
+managed auth fills **direct logins** from 1password items: username and password credentials plus any totp field for 2fa. these flows can be eligible for automatic reauthentication, including totp when its secret is stored in 1password. a later email or sms challenge, approval, or account choice can still require a new interactive login. direct logins include signing into an identity provider itself, such as a google account with its stored username, password, and totp. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery.
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.
From dbbe73fd3544ce70bff8aac991889ca78faa39fd Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 19:05:23 -0700
Subject: [PATCH 20/27] Apply suggestion from @AnnaXWang
---
auth/overview.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 27a77e00..f552e533 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -22,7 +22,7 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
| --- | --- | --- |
| **login navigation** | your application or agent | KERNEL |
| **where login happens** | in your agent’s current browser session | in a separate browser session managed by KERNEL |
-| **example use cases** | agents that do work on behalf of an end user, using the end user's credentials | recurring website qa on a set of known sites |
+| **example use cases** | ai assistants that do work on behalf of an end user, using the end user's credentials | recurring website qa on a set of known sites |
| **credential collection** | KERNEL-hosted collection form or your trusted backend | Managed Auth credential, Hosted UI, React component, or programmatic flow |
| **form filling and submission** | KERNEL fills the selected fields; your application or agent submits the form | KERNEL |
| **site response handling** | your application or agent | KERNEL |
From 13adebc53a1be8364ec7f53b87750a7a5bf18ac6 Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 19:08:16 -0700
Subject: [PATCH 21/27] Apply suggestion from @AnnaXWang
---
auth/managed-auth.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/auth/managed-auth.mdx b/auth/managed-auth.mdx
index 28d3e3f4..b415fa02 100644
--- a/auth/managed-auth.mdx
+++ b/auth/managed-auth.mdx
@@ -3,7 +3,7 @@ title: "Overview"
description: "Handle website login, reuse session state, and recover eligible connections automatically"
---
-managed auth handles website login and saves authenticated state to a reusable browser profile for your agents. KERNEL monitors the connection and can attempt automatic reauthentication for eligible flows that can complete without human input. if a site requires an email code, sms code, approval, or another user action, your application must start a new interactive login and bring the user back to complete it before the automation can continue.
+managed auth handles website login and saves authenticated state to a reusable browser profile for your agents. KERNEL monitors the connection and can attempt automatic reauthentication for eligible flows that can complete without human input.
use managed auth when you want KERNEL to orchestrate login and session recovery, and your application can bring the user back when authentication requires their input. use [vaults + credential fill](/auth/credential-fill) when your application or agent needs to control navigation, credential filling, submission, and recovery in its current browser session.
From a2b2fb35a2f6abb08a8c36ff1b9adb7a3d2f045b Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Wed, 16 Sep 2026 02:19:24 +0000
Subject: [PATCH 22/27] Clarify auth comparison and share credential fill
examples
---
auth/credential-fill.mdx | 49 +++--
auth/managed-auth.mdx | 2 +-
auth/overview.mdx | 18 +-
...use-vault-credentials-in-browser-agent.mdx | 171 +-----------------
snippets/attach-credential-vault.mdx | 16 ++
snippets/collect-browser-credentials.mdx | 60 ++++++
snippets/create-credential-vault.mdx | 22 +++
snippets/fill-browser-credentials.mdx | 64 +++++++
vaults/fill.mdx | 8 +-
9 files changed, 217 insertions(+), 193 deletions(-)
create mode 100644 snippets/attach-credential-vault.mdx
create mode 100644 snippets/collect-browser-credentials.mdx
create mode 100644 snippets/create-credential-vault.mdx
create mode 100644 snippets/fill-browser-credentials.mdx
diff --git a/auth/credential-fill.mdx b/auth/credential-fill.mdx
index 323f863a..b471ae5f 100644
--- a/auth/credential-fill.mdx
+++ b/auth/credential-fill.mdx
@@ -3,18 +3,23 @@ title: "Overview"
description: "Collect end-user credentials and inject them into browser forms while controlling the login workflow"
---
-Vaults + Credential Fill gives your application or agent direct control over authentication when an end user supplies credentials during a task. use KERNEL fill instead of injecting values directly so your controller sends field names and selectors rather than credential values. KERNEL reads the encrypted item, writes the selected values into the browser, and returns value-free outcomes. this keeps credentials out of agent prompts and browser-automation payloads while your workflow retains control of navigation, submission, and recovery.
+import CreateCredentialVault from "/snippets/create-credential-vault.mdx";
+import AttachCredentialVault from "/snippets/attach-credential-vault.mdx";
+import CollectBrowserCredentials from "/snippets/collect-browser-credentials.mdx";
+import FillBrowserCredentials from "/snippets/fill-browser-credentials.mdx";
+
+vaults + credential fill is an integration path where your application or agent controls the login workflow. vaults store encrypted credential items. the `fill` api operation writes selected values from an item into browser fields. your application or agent owns navigation, field selection, submission, and recovery.
start with the [end-user auth workflow cookbook](/browsers/use-vault-credentials-in-browser-agent) for an end-to-end example of secure collection, browser attachment, credential fill, form submission, and cleanup.
-KERNEL collects credential values or accepts them from a trusted backend, encrypts them in a credential item, and fills selected browser fields without including the values in the fill request or response. Your application or agent decides where to navigate, which fields to fill, when to submit, and how to handle the site's response.
+KERNEL collects credential values from the user or accepts them from a trusted backend. when invoking `fill`, your controller sends field names and selectors rather than credential values. KERNEL reads the encrypted item and returns value-free outcomes, keeping stored secrets out of agent prompts and browser-automation payloads.
- Credential Fill only writes stored values into fields you select. it doesn't discover fields, navigate, submit forms, verify authentication, monitor the session, or reauthenticate. your application or agent owns each of those steps.
+ `fill` only writes stored values into fields you select. it doesn't discover fields, navigate, submit forms, verify authentication, monitor the session, or reauthenticate. your application or agent owns each of those steps.
- fill writes real values into the browser. Page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them after filling.
+ `fill` writes real values into the browser. page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them after filling.
## When to use it
@@ -28,37 +33,53 @@ Vaults + Credential Fill works best when:
- your application or agent already handles browser navigation and site-specific recovery.
- you don't need KERNEL to monitor the session or reauthenticate it automatically.
-Choose [Managed Auth](/auth/managed-auth) instead when you want KERNEL to run the login flow, save the authenticated state, monitor the connection, and reauthenticate eligible flows.
+choose [managed auth](/auth/managed-auth) instead when you want KERNEL to run the login flow, save the authenticated state, monitor the connection, and attempt reauthentication for eligible flows.
## How it works
+these examples continue in order, using hacker news as the login destination. set `KERNEL_API_KEY` in your trusted backend environment. all examples use the default project; keep the vault and browser in the same project if you select a different one.
+
create a [vault](/vaults/overview) for each end user or credential-sharing boundary. A vault groups the items that an attached browser session can use.
-
-
- define a [credential item](/vaults/credentials), then collect values through a KERNEL-hosted form or copy them from a trusted backend. Sensitive values aren't returned by the vault api.
+
+
attach the vault when you create the browser. The attachment can't change during the session and grants access to every item in that vault.
+
+
-
- navigate to the login page, identify the fields, and invoke [fill](/vaults/fill) with field names and selectors. KERNEL writes the stored values into the selected inputs.
+
+ your application or agent navigates to the login page and identifies its fields before defining a [credential item](/vaults/credentials). hacker news has both login and create-account forms; the selectors in the next step target the login form. inspect the page and recheck them if it changes.
+
+
+
+ present the collection url only in the intended user's authenticated interface or private conversation. don't log it or open it in the agent-controlled browser. wait for the user to finish before continuing. an existing ready item may omit the collection action; reuse it or follow [credential collection](/vaults/credentials#collect-values-from-the-user) to reopen the form.
+
+
+ retrieve the same item, require readiness and an advertised `fill` operation, then invoke [`fill`](/vaults/fill) with field names and selectors. readiness means values exist, not that the website has accepted them. your application must authorize the destination before filling.
+
+
+
+ `completed` means the selected fields were filled, not that login succeeded. if `fill` fails, returns an uncertain outcome, or loses its response, stop and [inspect the outcome](/vaults/fill#handle-the-outcome) rather than automatically retrying.
- your application or agent submits the form and interprets the result. Fill doesn't submit the form or confirm that authentication succeeded.
+ after `fill` completes, your application or agent submits the login form once and verifies the site's response. `fill` doesn't perform either step. handle any additional authentication prompts before continuing the task.
+
+ delete the demo browser when finished, and delete the vault only if you created it for this demo and no longer need its credentials. see the [cookbook](/browsers/use-vault-credentials-in-browser-agent) for the complete agent handoff and cleanup guidance.
## Credential sources
-you can collect values from an end user with KERNEL's hosted collection form or [copy them from an existing credential vault](/vaults/existing-credential-vault) that your trusted backend can read. Both paths create the same ready credential item and use the same fill operation.
+you can collect values from an end user with KERNEL's hosted collection form or [copy them from an existing credential vault](/vaults/existing-credential-vault) that your trusted backend can read. both paths produce a ready credential item and use the same `fill` operation.
-Today, copying values stores an encrypted KERNEL copy. Credential Fill doesn't accept raw values or a third-party vault reference in the fill request.
+today, copying values stores an encrypted KERNEL copy. `fill` doesn't accept raw values or a third-party vault reference in its request.
## Session state
-Credential Fill completes one part of the workflow. It doesn't monitor the resulting session or reauthenticate it later. If you want to reuse the authenticated state, create the browser with a [profile](/auth/profiles) and save its changes after the login succeeds.
+`fill` completes one part of the workflow. it doesn't monitor the resulting session or reauthenticate it later. if you want to reuse the authenticated state, create the browser with a [profile](/auth/profiles) and save its changes after the login succeeds.
## Next steps
diff --git a/auth/managed-auth.mdx b/auth/managed-auth.mdx
index b415fa02..859e71a2 100644
--- a/auth/managed-auth.mdx
+++ b/auth/managed-auth.mdx
@@ -8,7 +8,7 @@ managed auth handles website login and saves authenticated state to a reusable b
use managed auth when you want KERNEL to orchestrate login and session recovery, and your application can bring the user back when authentication requires their input. use [vaults + credential fill](/auth/credential-fill) when your application or agent needs to control navigation, credential filling, submission, and recovery in its current browser session.
- with health checks and automatic reauthentication enabled, KERNEL automatically attempts to reauthenticate when a scheduled health check confirms a logged-out session and the connection is eligible (`can_reauth: true`). eligibility isn't a guarantee of success. if a blocking requirement is already known, an automatic attempt may not run at all. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery.
+ with automatic recovery enabled, KERNEL can attempt to sign in again when a health check confirms that a session has expired. recovery isn't guaranteed. if the site requires an email or sms code, approval, or another user action, your application must bring the user back to complete a new login. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery details.
## How it works
diff --git a/auth/overview.mdx b/auth/overview.mdx
index f552e533..7b091fe4 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -20,14 +20,12 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
| | Vaults + Credential Fill | Managed Auth |
| --- | --- | --- |
-| **login navigation** | your application or agent | KERNEL |
+| **login orchestration** | your application or agent owns navigation, submission, and response handling | KERNEL runs the login flow and requests user input when needed |
| **where login happens** | in your agent’s current browser session | in a separate browser session managed by KERNEL |
-| **example use cases** | ai assistants that do work on behalf of an end user, using the end user's credentials | recurring website qa on a set of known sites |
| **credential collection** | KERNEL-hosted collection form or your trusted backend | Managed Auth credential, Hosted UI, React component, or programmatic flow |
-| **form filling and submission** | KERNEL fills the selected fields; your application or agent submits the form | KERNEL |
-| **site response handling** | your application or agent | KERNEL |
+| **credential filling** | your application invokes `fill` with field names and selectors | KERNEL fills credentials as part of the managed login flow |
| **session state** | your workflow can save the resulting state to a profile | saved to a reusable profile |
-| **ongoing lifecycle** | your workflow decides when to authenticate again | health checks and eligible automatic reauthentication |
+| **ongoing recovery** | your workflow decides when and how to authenticate again | health checks and eligible automatic reauthentication attempts; your application brings the user back when input is required |
credential ownership is a useful starting point, but the main difference is who controls the login flow. Managed Auth can collect credentials from an end user. Vaults + Credential Fill is the lower-level option when your product needs to own navigation, submission, and recovery.
@@ -37,18 +35,14 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
### Use Vaults + Credential Fill
-- an authentication prompt can appear in the middle of a longer workflow, in the same browser session.
-- your product needs to control when and how it asks for credentials.
-- your application or agent must own navigation, submission, and recovery.
+- **ai assistants:** an assistant doing work on behalf of an end user can ask them to sign in during a task, such as downloading an invoice. your application or agent controls credential collection and completes the login in its current browser session.
### Use Managed Auth
-- the automation runs unattended or signs in repeatedly.
-- you want KERNEL to navigate common login, sso, and mfa flows.
-- you want health checks and eligible automatic reauthentication.
+- **recurring website qa:** reuse authenticated profiles to test account pages on a set of known sites. KERNEL handles the login flow and attempts eligible automatic recovery; your application must bring the user back if the site requires a code or approval.
- when Managed Auth detects a logged-out session during a health check, KERNEL automatically attempts to reauthenticate if the connection is eligible (`can_reauth: true`). this is an attempt, not a guarantee of success. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery when human input is required.
+ with automatic recovery enabled, KERNEL can attempt to sign in again when a health check confirms that a session has expired. recovery isn't guaranteed. if the site requires an email or sms code, approval, or another user action, your application must bring the user back to complete a new login. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery details.
## Understand the security boundary
diff --git a/browsers/use-vault-credentials-in-browser-agent.mdx b/browsers/use-vault-credentials-in-browser-agent.mdx
index 9883d080..5dfbcf41 100644
--- a/browsers/use-vault-credentials-in-browser-agent.mdx
+++ b/browsers/use-vault-credentials-in-browser-agent.mdx
@@ -3,6 +3,11 @@ title: "Build an End-User Auth Workflow"
description: "Collect credentials from a human, then fill browser forms without passing raw values to your agent"
---
+import CreateCredentialVault from "/snippets/create-credential-vault.mdx";
+import AttachCredentialVault from "/snippets/attach-credential-vault.mdx";
+import CollectBrowserCredentials from "/snippets/collect-browser-credentials.mdx";
+import FillBrowserCredentials from "/snippets/fill-browser-credentials.mdx";
+
this is the end-to-end cookbook for the [Vaults + Credential Fill](/auth/credential-fill) auth path. it covers secure collection, browser attachment, credential fill, form submission, and cleanup while your application or agent controls the workflow.
## What you need
@@ -64,49 +69,13 @@ a vault groups one user's credentials. use an immutable name tied to that user i
all examples use the default project; use the same project for the vault and browser if you select a different one.
-
-
-```typescript TypeScript
-import Kernel from "@onkernel/sdk";
-
-const kernel = new Kernel();
-const vault = await kernel.vaults.upsert({ name: "user-12345" });
-```
-
-```python Python
-from kernel import Kernel
-
-kernel = Kernel()
-vault = kernel.vaults.upsert(name="user-12345")
-```
-
-```bash CLI
-VAULT_NAME="user-12345"
-kernel vaults create --name "$VAULT_NAME"
-```
-
-
+
## 2. Create a browser with the vault attached
attach the vault when you create the browser. the attachment can't change afterward and grants access to all items in that vault, including credentials added later.
-
-
-```typescript TypeScript
-const browser = await kernel.browsers.create({ vaults: [{ id: vault.id }] });
-```
-
-```python Python
-browser = kernel.browsers.create(vaults=[{"id": vault.id}])
-```
-
-```bash CLI
-kernel browsers create --vault "$VAULT_NAME" -o json
-read -r -p "paste the returned session_id: " BROWSER_ID
-```
-
-
+
use the returned browser session id for fill, not a browser name. the interactive `read` saves it for the shell examples below; an agent can retain the returned id directly.
@@ -116,66 +85,7 @@ navigate to the login page and inspect the inputs before defining the credential
create a field definition for each required input, leaving its value unset. use only the recognizable site name for `description`, and mark ordinary usernames or email addresses `sensitive: false`.
-
-
-```typescript TypeScript
-await kernel.browsers.playwright.execute(browser.session_id, {
- code: "await page.goto('https://news.ycombinator.com/login'); return await page.title();",
-});
-const item = await kernel.vaults.items.upsert("hn-login", {
- id_or_name: vault.id,
- type: "credential",
- spec: {
- description: "Hacker News",
- fields: {
- username: { type: "text", required: true, sensitive: false },
- password: { type: "password", required: true, sensitive: true },
- },
- },
-});
-if (item.type !== "credential") throw new Error("expected a credential item");
-const collectionURL = item.action?.url;
-// Show collectionURL only to the intended user, not in general application logs.
-```
-
-```python Python
-kernel.browsers.playwright.execute(
- browser.session_id,
- code="await page.goto('https://news.ycombinator.com/login'); return await page.title();",
-)
-item = kernel.vaults.items.upsert(
- "hn-login",
- id_or_name=vault.id,
- type="credential",
- spec={
- "description": "Hacker News",
- "fields": {
- "username": {"type": "text", "required": True, "sensitive": False},
- "password": {"type": "password", "required": True, "sensitive": True},
- },
- },
-)
-if item.type != "credential":
- raise RuntimeError("expected a credential item")
-collection_url = item.action.url if item.action else None
-# Show collection_url only to the intended user, not in general application logs.
-```
-
-```bash CLI
-kernel browsers playwright execute "$BROWSER_ID" \
- "await page.goto('https://news.ycombinator.com/login'); return await page.title();"
-kernel vaults credentials create "$VAULT_NAME" hn-login --spec-file - <<'JSON'
-{
- "description": "Hacker News",
- "fields": {
- "username": {"type": "text", "required": true, "sensitive": false},
- "password": {"type": "password", "required": true, "sensitive": true}
- }
-}
-JSON
-```
-
-
+
the new item is `pending_collection` and returns a collection url. present it to the user and wait for their confirmation before continuing. in an application, render the url directly in the user's authenticated interface. the cli prompt above instead relays the link in a private conversation. don't open collection in the agent-controlled browser.
@@ -185,70 +95,7 @@ an existing ready item may omit the action. reuse it, or invoke the advertised `
retrieve the item after the user confirms collection. `ready` means required values exist, not that login succeeded. invoke only an advertised `fill` operation, with the exact current page url and unique input selectors. no credential values appear in the fill request.
-
-
-```typescript TypeScript
-const current = await kernel.vaults.items.retrieve(item.key, {
- id_or_name: vault.id,
- wait: 60,
-});
-if (current.id !== item.id || current.type !== "credential" ||
- current.state.status !== "ready" ||
- !current.available_operations.some((operation) => operation.type === "fill")) {
- throw new Error("credential is not ready to fill");
-}
-const result = await kernel.vaults.items.performOperation(item.key, {
- id_or_name: vault.id,
- type: "fill",
- browser_id: browser.session_id,
- page_url: "https://news.ycombinator.com/login",
- fields: [
- { field: "username", selector: "form:has(input[autocomplete='current-password']) input[name='acct']" },
- { field: "password", selector: "input[autocomplete='current-password']" },
- ],
-});
-if (result.type !== "fill" || result.status !== "completed") {
- throw new Error("stop and reconcile the fill outcome");
-}
-```
-
-```python Python
-current = kernel.vaults.items.retrieve(item.key, id_or_name=vault.id, wait=60)
-if (current.id != item.id or current.type != "credential" or
- current.state.status != "ready" or
- not any(operation.type == "fill" for operation in current.available_operations)):
- raise RuntimeError("credential is not ready to fill")
-result = kernel.vaults.items.perform_operation(
- item.key,
- id_or_name=vault.id,
- type="fill",
- browser_id=browser.session_id,
- page_url="https://news.ycombinator.com/login",
- fields=[
- {"field": "username", "selector": "form:has(input[autocomplete='current-password']) input[name='acct']"},
- {"field": "password", "selector": "input[autocomplete='current-password']"},
- ],
-)
-if result.type != "fill" or result.status != "completed":
- raise RuntimeError("stop and reconcile the fill outcome")
-```
-
-```bash CLI
-kernel vaults items get "$VAULT_NAME" hn-login --wait 60 -o json
-# Continue only if the same item is ready and advertises fill.
-kernel vaults items invoke "$VAULT_NAME" hn-login fill --spec-file - <
+
if the result is `completed`, the agent can submit login once and inspect the site's response. filling doesn't submit the form or confirm authentication. if the operation fails, returns `unknown`, or loses its response, stop instead of retrying. the [fill guide](/vaults/fill#handle-the-outcome) explains partial outcomes.
diff --git a/snippets/attach-credential-vault.mdx b/snippets/attach-credential-vault.mdx
new file mode 100644
index 00000000..c4cf15bc
--- /dev/null
+++ b/snippets/attach-credential-vault.mdx
@@ -0,0 +1,16 @@
+
+
+```typescript TypeScript
+const browser = await kernel.browsers.create({ vaults: [{ id: vault.id }] });
+```
+
+```python Python
+browser = kernel.browsers.create(vaults=[{"id": vault.id}])
+```
+
+```bash CLI
+kernel browsers create --vault "$VAULT_NAME" -o json
+read -r -p "paste the returned session_id: " BROWSER_ID
+```
+
+
diff --git a/snippets/collect-browser-credentials.mdx b/snippets/collect-browser-credentials.mdx
new file mode 100644
index 00000000..dc6c4abb
--- /dev/null
+++ b/snippets/collect-browser-credentials.mdx
@@ -0,0 +1,60 @@
+
+
+```typescript TypeScript
+await kernel.browsers.playwright.execute(browser.session_id, {
+ code: "await page.goto('https://news.ycombinator.com/login'); return await page.title();",
+});
+const item = await kernel.vaults.items.upsert("hn-login", {
+ id_or_name: vault.id,
+ type: "credential",
+ spec: {
+ description: "Hacker News",
+ fields: {
+ username: { type: "text", required: true, sensitive: false },
+ password: { type: "password", required: true, sensitive: true },
+ },
+ },
+});
+if (item.type !== "credential") throw new Error("expected a credential item");
+const collectionURL = item.action?.url;
+// Show collectionURL only to the intended user, not in general application logs.
+```
+
+```python Python
+kernel.browsers.playwright.execute(
+ browser.session_id,
+ code="await page.goto('https://news.ycombinator.com/login'); return await page.title();",
+)
+item = kernel.vaults.items.upsert(
+ "hn-login",
+ id_or_name=vault.id,
+ type="credential",
+ spec={
+ "description": "Hacker News",
+ "fields": {
+ "username": {"type": "text", "required": True, "sensitive": False},
+ "password": {"type": "password", "required": True, "sensitive": True},
+ },
+ },
+)
+if item.type != "credential":
+ raise RuntimeError("expected a credential item")
+collection_url = item.action.url if item.action else None
+# Show collection_url only to the intended user, not in general application logs.
+```
+
+```bash CLI
+kernel browsers playwright execute "$BROWSER_ID" \
+ "await page.goto('https://news.ycombinator.com/login'); return await page.title();"
+kernel vaults credentials create "$VAULT_NAME" hn-login --spec-file - <<'JSON'
+{
+ "description": "Hacker News",
+ "fields": {
+ "username": {"type": "text", "required": true, "sensitive": false},
+ "password": {"type": "password", "required": true, "sensitive": true}
+ }
+}
+JSON
+```
+
+
diff --git a/snippets/create-credential-vault.mdx b/snippets/create-credential-vault.mdx
new file mode 100644
index 00000000..0243cec8
--- /dev/null
+++ b/snippets/create-credential-vault.mdx
@@ -0,0 +1,22 @@
+
+
+```typescript TypeScript
+import Kernel from "@onkernel/sdk";
+
+const kernel = new Kernel();
+const vault = await kernel.vaults.upsert({ name: "user-12345" });
+```
+
+```python Python
+from kernel import Kernel
+
+kernel = Kernel()
+vault = kernel.vaults.upsert(name="user-12345")
+```
+
+```bash CLI
+VAULT_NAME="user-12345"
+kernel vaults create --name "$VAULT_NAME"
+```
+
+
diff --git a/snippets/fill-browser-credentials.mdx b/snippets/fill-browser-credentials.mdx
new file mode 100644
index 00000000..d6d1bec5
--- /dev/null
+++ b/snippets/fill-browser-credentials.mdx
@@ -0,0 +1,64 @@
+
+
+```typescript TypeScript
+const current = await kernel.vaults.items.retrieve(item.key, {
+ id_or_name: vault.id,
+ wait: 60,
+});
+if (current.id !== item.id || current.type !== "credential" ||
+ current.state.status !== "ready" ||
+ !current.available_operations.some((operation) => operation.type === "fill")) {
+ throw new Error("credential is not ready to fill");
+}
+const result = await kernel.vaults.items.performOperation(item.key, {
+ id_or_name: vault.id,
+ type: "fill",
+ browser_id: browser.session_id,
+ page_url: "https://news.ycombinator.com/login",
+ fields: [
+ { field: "username", selector: "form:has(input[autocomplete='current-password']) input[name='acct']" },
+ { field: "password", selector: "input[autocomplete='current-password']" },
+ ],
+});
+if (result.type !== "fill" || result.status !== "completed") {
+ throw new Error("stop and reconcile the fill outcome");
+}
+```
+
+```python Python
+current = kernel.vaults.items.retrieve(item.key, id_or_name=vault.id, wait=60)
+if (current.id != item.id or current.type != "credential" or
+ current.state.status != "ready" or
+ not any(operation.type == "fill" for operation in current.available_operations)):
+ raise RuntimeError("credential is not ready to fill")
+result = kernel.vaults.items.perform_operation(
+ item.key,
+ id_or_name=vault.id,
+ type="fill",
+ browser_id=browser.session_id,
+ page_url="https://news.ycombinator.com/login",
+ fields=[
+ {"field": "username", "selector": "form:has(input[autocomplete='current-password']) input[name='acct']"},
+ {"field": "password", "selector": "input[autocomplete='current-password']"},
+ ],
+)
+if result.type != "fill" or result.status != "completed":
+ raise RuntimeError("stop and reconcile the fill outcome")
+```
+
+```bash CLI
+kernel vaults items get "$VAULT_NAME" hn-login --wait 60 -o json
+# Continue only if the same item is ready and advertises fill.
+kernel vaults items invoke "$VAULT_NAME" hn-login fill --spec-file - <
diff --git a/vaults/fill.mdx b/vaults/fill.mdx
index e8fceef4..40f0e368 100644
--- a/vaults/fill.mdx
+++ b/vaults/fill.mdx
@@ -3,7 +3,7 @@ title: "Fill Browser Fields"
description: "Map vault fields to browser inputs without returning their values to your application"
---
-invoke an item's `fill` operation to write selected values into an attached browser. your request contains field names and css selectors, not credential values. the result reports outcomes without returning the values. fill is the credential injection step in the [Vaults + Credential Fill](/auth/credential-fill) auth path.
+invoke an item's `fill` operation to write selected values into an attached browser. your request contains field names and css selectors, not credential values. the result reports outcomes without returning the values. `fill` is the credential injection step in the [Vaults + Credential Fill](/auth/credential-fill) auth path.
`fill` reads credentials from a ready KERNEL credential item. if another vault
@@ -14,7 +14,7 @@ invoke an item's `fill` operation to write selected values into an attached brow
- fill writes real values into the browser. page scripts, extensions, devtools, and an agent with unrestricted browser access may read them.
+ `fill` writes real values into the browser. page scripts, extensions, devtools, and an agent with unrestricted browser access may read them.
## Check availability
@@ -99,8 +99,8 @@ KERNEL validates bindings before writing, then fills in request order. if naviga
known execution failures can return http `200` with a `failed` or `unknown` status. inspect the response body, not only the http status. each entry in `fields` identifies its request binding by zero-based `index` and reports `filled`, `failed`, `unknown`, or `not_attempted`. bindings after the first failed or unknown field are `not_attempted`.
-fill doesn't click buttons or submit forms, but input/change handlers can trigger site behavior. `completed` doesn't mean login succeeded or a form was submitted.
+`fill` doesn't click buttons or submit forms, but input/change handlers can trigger site behavior. `completed` doesn't mean login succeeded or a form was submitted.
-**don't automatically retry fill after a failure or uncertain outcome.** a lost response can follow successful writes; another request can repeat events, overwrite edits, or generate a different totp code. deliberate recovery starts with inspecting the existing attempt, not replaying it.
+**don't automatically retry `fill` after a failure or uncertain outcome.** a lost response can follow successful writes; another request can repeat events, overwrite edits, or generate a different totp code. deliberate recovery starts with inspecting the existing attempt, not replaying it.
for the full application and agent handoff, follow [use vault credentials in a browser agent](/browsers/use-vault-credentials-in-browser-agent).
From 261e67eefc47d155d7a1aa27b64692af99d79fb1 Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Tue, 15 Sep 2026 19:44:33 -0700
Subject: [PATCH 23/27] Apply batched suggestions from code review
Co-authored-by: Anna Wang
---
auth/credential-fill.mdx | 4 +---
auth/overview.mdx | 15 ++++++++++-----
2 files changed, 11 insertions(+), 8 deletions(-)
diff --git a/auth/credential-fill.mdx b/auth/credential-fill.mdx
index b471ae5f..6972f780 100644
--- a/auth/credential-fill.mdx
+++ b/auth/credential-fill.mdx
@@ -26,9 +26,7 @@ KERNEL collects credential values from the user or accepts them from a trusted b
Vaults + Credential Fill works best when:
-- you're building an ai assistant that asks users to sign in during a task, such as downloading an invoice from their account, while retaining control of the browser workflow.
-- an end user owns the credentials and remains present during the task.
-- a login or authentication prompt can appear in the middle of a workflow.
+- a login or authentication prompt can appear in the middle of a workflow, in the same browser session.
- your product needs to control the credential collection experience.
- your application or agent already handles browser navigation and site-specific recovery.
- you don't need KERNEL to monitor the session or reauthenticate it automatically.
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 7b091fe4..548f3eae 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -27,19 +27,24 @@ most useful browser workflows begin behind a login. KERNEL gives you two ways to
| **session state** | your workflow can save the resulting state to a profile | saved to a reusable profile |
| **ongoing recovery** | your workflow decides when and how to authenticate again | health checks and eligible automatic reauthentication attempts; your application brings the user back when input is required |
-
- credential ownership is a useful starting point, but the main difference is who controls the login flow. Managed Auth can collect credentials from an end user. Vaults + Credential Fill is the lower-level option when your product needs to own navigation, submission, and recovery.
-
## Common use cases
### Use Vaults + Credential Fill
-- **ai assistants:** an assistant doing work on behalf of an end user can ask them to sign in during a task, such as downloading an invoice. your application or agent controls credential collection and completes the login in its current browser session.
+- an authentication prompt can appear in the middle of a longer workflow, in the same browser session.
+- your product needs to control when and how it asks for credentials.
+- your application or agent must own navigation, submission, and recovery.
+
+one common use case is an ai assistant doing work on behalf of an end user. with vaults and credential fill, the agent can login as the user to complete tasks on gated websites. your application or agent controls credential collection and completes the login in its current browser session.
### Use Managed Auth
-- **recurring website qa:** reuse authenticated profiles to test account pages on a set of known sites. KERNEL handles the login flow and attempts eligible automatic recovery; your application must bring the user back if the site requires a code or approval.
+- the automation runs unattended or signs in repeatedly.
+- you want KERNEL to navigate common login, sso, and mfa flows.
+- you want health checks and eligible automatic reauthentication.
+
+one common use case is recurring website qa on a set of known sites. KERNEL handles the login flow and attempts eligible automatic recovery before the automation begins. the automation can start testing on websites without needing to login.
with automatic recovery enabled, KERNEL can attempt to sign in again when a health check confirms that a session has expired. recovery isn't guaranteed. if the site requires an email or sms code, approval, or another user action, your application must bring the user back to complete a new login. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery details.
From 0b7d207c6eb57e968adf9659ef86632b9c51de6b Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Wed, 16 Sep 2026 09:05:10 -0700
Subject: [PATCH 24/27] Apply suggestion from @AnnaXWang
---
auth/overview.mdx | 2 ++
1 file changed, 2 insertions(+)
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 548f3eae..755a5fb8 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -5,6 +5,8 @@ description: "Choose how your browser agents authenticate and reuse signed-in se
most useful browser workflows begin behind a login. KERNEL gives you two ways to authenticate browser agents without returning stored sensitive values through the api or putting them in your agent prompt: control the workflow yourself with Vaults + Credential Fill, or delegate the login and session lifecycle to Managed Auth.
+Vaults + Fill is the recommended approach if you require greater visibility and control over the authentication experience, while Managed Auth is preferred if you would like KERNEL to handle the login lifecycle on your behalf.
+
## Choose an auth approach
From 30354198b915998b6960ae3d12743c680079d1cb Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Wed, 16 Sep 2026 10:16:37 -0700
Subject: [PATCH 25/27] Apply batched suggestions from code review
Co-authored-by: plee
---
auth/credential-fill.mdx | 4 ++--
auth/overview.mdx | 12 ++++++------
2 files changed, 8 insertions(+), 8 deletions(-)
diff --git a/auth/credential-fill.mdx b/auth/credential-fill.mdx
index 6972f780..6a3b10ae 100644
--- a/auth/credential-fill.mdx
+++ b/auth/credential-fill.mdx
@@ -8,7 +8,7 @@ import AttachCredentialVault from "/snippets/attach-credential-vault.mdx";
import CollectBrowserCredentials from "/snippets/collect-browser-credentials.mdx";
import FillBrowserCredentials from "/snippets/fill-browser-credentials.mdx";
-vaults + credential fill is an integration path where your application or agent controls the login workflow. vaults store encrypted credential items. the `fill` api operation writes selected values from an item into browser fields. your application or agent owns navigation, field selection, submission, and recovery.
+Fill from Vaults is an integration path where your application or agent controls the login workflow. vaults store encrypted credential items. the `fill` api operation writes selected values from an item into browser fields. your application or agent owns navigation, field selection, submission, and recovery.
start with the [end-user auth workflow cookbook](/browsers/use-vault-credentials-in-browser-agent) for an end-to-end example of secure collection, browser attachment, credential fill, form submission, and cleanup.
@@ -24,7 +24,7 @@ KERNEL collects credential values from the user or accepts them from a trusted b
## When to use it
-Vaults + Credential Fill works best when:
+Fill from Vaults works best when:
- a login or authentication prompt can appear in the middle of a workflow, in the same browser session.
- your product needs to control the credential collection experience.
diff --git a/auth/overview.mdx b/auth/overview.mdx
index 755a5fb8..f6b4b928 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -3,14 +3,14 @@ title: "Overview"
description: "Choose how your browser agents authenticate and reuse signed-in sessions"
---
-most useful browser workflows begin behind a login. KERNEL gives you two ways to authenticate browser agents without returning stored sensitive values through the api or putting them in your agent prompt: control the workflow yourself with Vaults + Credential Fill, or delegate the login and session lifecycle to Managed Auth.
+most useful browser workflows begin behind a login. KERNEL gives you two ways to authenticate browser agents without returning stored sensitive values through the api or putting them in your agent prompt: control the workflow yourself and Fill from Vault, or delegate the login and session lifecycle to Managed Auth.
-Vaults + Fill is the recommended approach if you require greater visibility and control over the authentication experience, while Managed Auth is preferred if you would like KERNEL to handle the login lifecycle on your behalf.
+Fill from Vault is the recommended approach if you require greater visibility and control over the authentication experience, while Managed Auth is preferred if you would like KERNEL to handle the login lifecycle on your behalf.
## Choose an auth approach
-
+
**control the login workflow**
@@ -20,7 +20,7 @@ Vaults + Fill is the recommended approach if you require greater visibility and
-| | Vaults + Credential Fill | Managed Auth |
+| | Fill from Vault | Managed Auth |
| --- | --- | --- |
| **login orchestration** | your application or agent owns navigation, submission, and response handling | KERNEL runs the login flow and requests user input when needed |
| **where login happens** | in your agent’s current browser session | in a separate browser session managed by KERNEL |
@@ -32,7 +32,7 @@ Vaults + Fill is the recommended approach if you require greater visibility and
## Common use cases
-### Use Vaults + Credential Fill
+### Use Fill from Vault
- an authentication prompt can appear in the middle of a longer workflow, in the same browser session.
- your product needs to control when and how it asks for credentials.
@@ -63,7 +63,7 @@ KERNEL doesn't return stored sensitive fields in api responses or add them to mo
## Next steps
-
+
collect end-user credentials and control navigation, form submission, and recovery in your own workflow.
From 574804a61bcca22ada4a21371a0728f2ee07a44e Mon Sep 17 00:00:00 2001
From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com>
Date: Wed, 16 Sep 2026 17:48:11 +0000
Subject: [PATCH 26/27] Rename Fill from Vault and reorganize browser
navigation
---
...redential-fill.mdx => fill-from-vault.mdx} | 6 +-
auth/managed-auth.mdx | 6 +-
auth/overview.mdx | 10 +--
...use-vault-credentials-in-browser-agent.mdx | 2 +-
docs.json | 80 ++++++++++---------
index.mdx | 2 +-
vaults/credentials.mdx | 2 +-
vaults/existing-credential-vault.mdx | 8 +-
vaults/fill.mdx | 2 +-
vaults/overview.mdx | 2 +-
10 files changed, 61 insertions(+), 59 deletions(-)
rename auth/{credential-fill.mdx => fill-from-vault.mdx} (93%)
diff --git a/auth/credential-fill.mdx b/auth/fill-from-vault.mdx
similarity index 93%
rename from auth/credential-fill.mdx
rename to auth/fill-from-vault.mdx
index d9f76d8d..509fa75c 100644
--- a/auth/credential-fill.mdx
+++ b/auth/fill-from-vault.mdx
@@ -8,9 +8,9 @@ import AttachCredentialVault from "/snippets/attach-credential-vault.mdx";
import CollectBrowserCredentials from "/snippets/collect-browser-credentials.mdx";
import FillBrowserCredentials from "/snippets/fill-browser-credentials.mdx";
-Fill from Vaults is an integration path where your application or agent controls the login workflow. vaults store encrypted credential items. the `fill` api operation writes selected values from an item into browser fields. your application or agent owns navigation, field selection, submission, and recovery.
+Fill from Vault is an integration path where your application or agent controls the login workflow. vaults store encrypted credential items. the `fill` api operation writes selected values from an item into browser fields. your application or agent owns navigation, field selection, submission, and recovery.
-start with the [end-user auth workflow cookbook](/browsers/use-vault-credentials-in-browser-agent) for an end-to-end example of secure collection, browser attachment, credential fill, form submission, and cleanup.
+start with the [end-user auth workflow cookbook](/browsers/use-vault-credentials-in-browser-agent) for an end-to-end example of secure collection, browser attachment, the `fill` operation, form submission, and cleanup.
KERNEL collects credential values from the user or accepts them from a trusted backend. when invoking `fill`, your controller sends field names and selectors rather than credential values. KERNEL reads the encrypted item and returns value-free outcomes, keeping stored secrets out of agent prompts and browser-automation payloads.
@@ -24,7 +24,7 @@ KERNEL collects credential values from the user or accepts them from a trusted b
## When to use it
-Fill from Vaults works best when:
+Fill from Vault works best when:
- a login or authentication prompt can appear in the middle of a workflow, in the same browser session.
- your product needs to control the credential collection experience.
diff --git a/auth/managed-auth.mdx b/auth/managed-auth.mdx
index f4edc981..8d1a0f4d 100644
--- a/auth/managed-auth.mdx
+++ b/auth/managed-auth.mdx
@@ -7,7 +7,7 @@ managed auth handles website login and saves authenticated state to a reusable b
managed auth stores authentication state in [browser profiles](/browsers/profiles). profiles can also persist and reuse browser state without managed auth.
-use managed auth when you want KERNEL to orchestrate login and session recovery, and your application can bring the user back when authentication requires their input. use [vaults + credential fill](/auth/credential-fill) when your application or agent needs to control navigation, credential filling, submission, and recovery in its current browser session.
+use managed auth when you want KERNEL to orchestrate login and session recovery, and your application can bring the user back when authentication requires their input. use [Fill from Vault](/auth/fill-from-vault) when your application or agent needs to control navigation, credential filling, submission, and recovery in its current browser session.
with automatic recovery enabled, KERNEL can attempt to sign in again when a health check confirms that a session has expired. recovery isn't guaranteed. if the site requires an email or sms code, approval, or another user action, your application must bring the user back to complete a new login. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery details.
@@ -217,6 +217,6 @@ The most valuable workflows live behind logins. Managed Auth provides:
| **Encrypted profiles** | Browser session state encrypted end-to-end |
| **Isolated execution** | Each login runs in an isolated browser environment |
-## When to use Vaults + Credential Fill
+## When to use Fill from Vault
-Use [Vaults + Credential Fill](/auth/credential-fill) when an end user owns the credentials, remains present during the task, and might need to respond to an authentication prompt mid-workflow. Your application or agent controls navigation, chooses the fields to fill, submits the form, and handles the site's response. KERNEL collects and stores sensitive values, then fills them without returning them through the api.
+Use [Fill from Vault](/auth/fill-from-vault) when an end user owns the credentials, remains present during the task, and might need to respond to an authentication prompt mid-workflow. Your application or agent controls navigation, chooses the fields to fill, submits the form, and handles the site's response. KERNEL collects and stores sensitive values, then fills them without returning them through the api.
diff --git a/auth/overview.mdx b/auth/overview.mdx
index a90665c3..a309a5d3 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -10,7 +10,7 @@ Fill from Vault is the recommended approach if you require greater visibility an
## Choose an auth approach
-
+
**control the login workflow**
@@ -38,7 +38,7 @@ Fill from Vault is the recommended approach if you require greater visibility an
- your product needs to control when and how it asks for credentials.
- your application or agent must own navigation, submission, and recovery.
-one common use case is an ai assistant doing work on behalf of an end user. with vaults and credential fill, the agent can login as the user to complete tasks on gated websites. your application or agent controls credential collection and completes the login in its current browser session.
+one common use case is an ai assistant doing work on behalf of an end user. with Fill from Vault, the agent can login as the user to complete tasks on gated websites. your application or agent controls credential collection and completes the login in its current browser session.
### Use Managed Auth
@@ -54,16 +54,16 @@ one common use case is recurring website qa on a set of known sites. KERNEL hand
## Understand the security boundary
-KERNEL doesn't return stored sensitive fields in api responses or add them to model context. Credential Fill writes real values into the browser. Page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them after fill. Use the narrowest browser permissions that your workflow supports, and only attach a vault to sessions authorized to use all of its items.
+KERNEL doesn't return stored sensitive fields in api responses or add them to model context. the `fill` operation writes real values into the browser. Page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them after fill. Use the narrowest browser permissions that your workflow supports, and only attach a vault to sessions authorized to use all of its items.
## Reuse authenticated state
-[Profiles](/browsers/profiles) persist cookies and local storage between browser sessions. Managed Auth saves successful logins to a profile automatically. A workflow using Vaults + Credential Fill can also save the resulting browser state to a profile when it needs to reuse that session.
+[Profiles](/browsers/profiles) persist cookies and local storage between browser sessions. Managed Auth saves successful logins to a profile automatically. A workflow using Fill from Vault can also save the resulting browser state to a profile when it needs to reuse that session.
## Next steps
-
+
collect end-user credentials and control navigation, form submission, and recovery in your own workflow.
diff --git a/browsers/use-vault-credentials-in-browser-agent.mdx b/browsers/use-vault-credentials-in-browser-agent.mdx
index 5dfbcf41..e1deeee4 100644
--- a/browsers/use-vault-credentials-in-browser-agent.mdx
+++ b/browsers/use-vault-credentials-in-browser-agent.mdx
@@ -8,7 +8,7 @@ import AttachCredentialVault from "/snippets/attach-credential-vault.mdx";
import CollectBrowserCredentials from "/snippets/collect-browser-credentials.mdx";
import FillBrowserCredentials from "/snippets/fill-browser-credentials.mdx";
-this is the end-to-end cookbook for the [Vaults + Credential Fill](/auth/credential-fill) auth path. it covers secure collection, browser attachment, credential fill, form submission, and cleanup while your application or agent controls the workflow.
+this is the end-to-end cookbook for the [Fill from Vault](/auth/fill-from-vault) auth path. it covers secure collection, browser attachment, the `fill` operation, form submission, and cleanup while your application or agent controls the workflow.
## What you need
diff --git a/docs.json b/docs.json
index e6a42eae..39ecf67e 100644
--- a/docs.json
+++ b/docs.json
@@ -10,6 +10,8 @@
{ "source": "/auth/agent/hosted-ui", "destination": "/auth/hosted-ui" },
{ "source": "/auth/agent/programmatic", "destination": "/auth/programmatic" },
{ "source": "/auth/agent/faq", "destination": "/auth/faq" },
+ { "source": "/auth/credential-fill", "destination": "/auth/fill-from-vault" },
+ { "source": "/auth/credential-fill.md", "destination": "/auth/fill-from-vault.md" },
{ "source": "/auth/credential-fill/existing-vault", "destination": "/vaults/existing-credential-vault" },
{ "source": "/auth/profiles", "destination": "/browsers/profiles" },
{ "source": "/auth/profiles.md", "destination": "/browsers/profiles.md" },
@@ -120,56 +122,56 @@
"browsers/termination",
"browsers/standby",
"browsers/headless",
- "info/projects"
- ]
- },
- {
- "group": "Profiles",
- "pages": [
- "browsers/profiles",
- "browsers/profiles/save-and-reuse",
- "browsers/profiles/concurrency",
- "browsers/profiles/agent-patterns"
+ "info/projects",
+ {
+ "group": "Profiles",
+ "pages": [
+ "browsers/profiles",
+ "browsers/profiles/save-and-reuse",
+ "browsers/profiles/concurrency",
+ "browsers/profiles/agent-patterns"
+ ]
+ }
]
},
{
- "group": "Auth",
+ "group": "Intermediate",
+ "expanded": true,
"pages": [
- "auth/overview",
{
- "group": "Vaults + Credential Fill",
+ "group": "Auth",
"pages": [
- "auth/credential-fill"
+ "auth/overview",
+ {
+ "group": "Fill from Vault",
+ "pages": [
+ "auth/fill-from-vault"
+ ]
+ },
+ {
+ "group": "Managed Auth",
+ "pages": [
+ "auth/managed-auth",
+ "auth/hosted-ui",
+ "auth/react",
+ "auth/programmatic",
+ "auth/configuration",
+ "auth/connection-lifecycle",
+ "auth/credentials",
+ "auth/faq"
+ ]
+ }
]
},
{
- "group": "Managed Auth",
+ "group": "Vaults",
"pages": [
- "auth/managed-auth",
- "auth/hosted-ui",
- "auth/react",
- "auth/programmatic",
- "auth/configuration",
- "auth/connection-lifecycle",
- "auth/credentials",
- "auth/faq"
+ "vaults/overview",
+ "vaults/credentials",
+ "vaults/existing-credential-vault",
+ "vaults/fill"
]
- }
- ]
- },
- {
- "group": "Vaults",
- "pages": [
- "vaults/overview",
- "vaults/credentials",
- "vaults/existing-credential-vault",
- "vaults/fill"
- ]
- },
- {
- "group": "Intermediate",
- "expanded": true,
- "pages": [
+ },
"browsers/replays",
"browsers/viewport",
"browsers/regions",
diff --git a/index.mdx b/index.mdx
index a9b63387..c3c3159e 100644
--- a/index.mdx
+++ b/index.mdx
@@ -12,7 +12,7 @@ We build crazy fast, open source infra for AI agents to access the internet. Tru
We spin up cloud browsers in <30ms with GPU acceleration when needed.
- Choose managed login flows or secure credential fill for browser agents.
+ choose Managed Auth or Fill from Vault for browser agents.
We solve CAPTCHAs and manage residential proxies to help you see fewer of them.
diff --git a/vaults/credentials.mdx b/vaults/credentials.mdx
index 85b2c7b7..6bc80c2a 100644
--- a/vaults/credentials.mdx
+++ b/vaults/credentials.mdx
@@ -3,7 +3,7 @@ title: "Credential Items"
description: "Collect and update encrypted credentials, then fill selected fields in a vault-attached browser"
---
-use a `credential` item for usernames, passwords, totp generators, and other non-payment credentials. it belongs directly to a [vault](/vaults/overview); you don't need a wallet or an external credential provider. credential items power the [Vaults + Credential Fill](/auth/credential-fill) path under Auth.
+use a `credential` item for usernames, passwords, totp generators, and other non-payment credentials. it belongs directly to a [vault](/vaults/overview); you don't need a wallet or an external credential provider. credential items power the [Fill from Vault](/auth/fill-from-vault) path under Auth.
use `wallet` and `card` items for credit card numbers, security codes, and expiration dates. don't store, collect, or fill payment-card data through credential items.
diff --git a/vaults/existing-credential-vault.mdx b/vaults/existing-credential-vault.mdx
index 843138dd..352a5e8f 100644
--- a/vaults/existing-credential-vault.mdx
+++ b/vaults/existing-credential-vault.mdx
@@ -3,10 +3,10 @@ title: "Use an Existing Credential Vault"
description: "Copy credentials from an existing vault into KERNEL for browser fill"
---
-keep an existing credential vault as your source of truth while using KERNEL to fill browser forms. this is the credential-source setup for [Vaults + Credential Fill](/auth/credential-fill): your trusted backend reads the source credential, copies it into a KERNEL credential item, and updates or deletes that copy as the source changes.
+keep an existing credential vault as your source of truth while using KERNEL to fill browser forms. this is the credential-source setup for [Fill from Vault](/auth/fill-from-vault): your trusted backend reads the source credential, copies it into a KERNEL credential item, and updates or deletes that copy as the source changes.
- Credential Fill doesn't currently read directly from a third-party vault or accept a provider reference in a fill request. KERNEL stores an encrypted copy of the values. Your backend is responsible for synchronization and deletion.
+ `fill` doesn't currently read directly from a third-party vault or accept a provider reference in a fill request. KERNEL stores an encrypted copy of the values. Your backend is responsible for synchronization and deletion.
## How it works
@@ -51,9 +51,9 @@ Keep the source credential's immutable identifier alongside the KERNEL vault and
KERNEL's [1Password integration](/integrations/1password) is specific to Managed Auth. Managed Auth retrieves matching values from 1Password when it authenticates and doesn't store them in KERNEL.
-Vaults + Credential Fill uses a different boundary:
+Fill from Vault uses a different boundary:
-| | Existing vault + Credential Fill | Managed Auth + 1Password |
+| | Fill from Vault with an existing vault | Managed Auth + 1Password |
| --- | --- | --- |
| **who reads the source** | your trusted backend | Managed Auth |
| **storage in KERNEL** | encrypted credential copy | values remain in 1Password |
diff --git a/vaults/fill.mdx b/vaults/fill.mdx
index 40f0e368..ca005e67 100644
--- a/vaults/fill.mdx
+++ b/vaults/fill.mdx
@@ -3,7 +3,7 @@ title: "Fill Browser Fields"
description: "Map vault fields to browser inputs without returning their values to your application"
---
-invoke an item's `fill` operation to write selected values into an attached browser. your request contains field names and css selectors, not credential values. the result reports outcomes without returning the values. `fill` is the credential injection step in the [Vaults + Credential Fill](/auth/credential-fill) auth path.
+invoke an item's `fill` operation to write selected values into an attached browser. your request contains field names and css selectors, not credential values. the result reports outcomes without returning the values. `fill` is the credential injection step in the [Fill from Vault](/auth/fill-from-vault) auth path.
`fill` reads credentials from a ready KERNEL credential item. if another vault
diff --git a/vaults/overview.mdx b/vaults/overview.mdx
index 0ab10456..34b9ec1e 100644
--- a/vaults/overview.mdx
+++ b/vaults/overview.mdx
@@ -16,7 +16,7 @@ non-sensitive stand-ins that KERNEL resolves at egress, outside the browser.
choose the path deliberately: their exposure boundaries differ.
for authentication workflows where your application or agent controls
-navigation and submission, start with [Vaults + Credential Fill](/auth/credential-fill).
+navigation and submission, start with [Fill from Vault](/auth/fill-from-vault).
fill isn't secret isolation from the browser. an agent with unrestricted
From 684114cb289f1666deb4a69a5aecafca0073ee56 Mon Sep 17 00:00:00 2001
From: Anna Wang
Date: Wed, 16 Sep 2026 10:54:07 -0700
Subject: [PATCH 27/27] Apply batched suggestions from code review
Co-authored-by: Anna Wang
---
auth/fill-from-vault.mdx | 5 +----
auth/overview.mdx | 3 ---
2 files changed, 1 insertion(+), 7 deletions(-)
diff --git a/auth/fill-from-vault.mdx b/auth/fill-from-vault.mdx
index 509fa75c..f81bbf4c 100644
--- a/auth/fill-from-vault.mdx
+++ b/auth/fill-from-vault.mdx
@@ -8,7 +8,7 @@ import AttachCredentialVault from "/snippets/attach-credential-vault.mdx";
import CollectBrowserCredentials from "/snippets/collect-browser-credentials.mdx";
import FillBrowserCredentials from "/snippets/fill-browser-credentials.mdx";
-Fill from Vault is an integration path where your application or agent controls the login workflow. vaults store encrypted credential items. the `fill` api operation writes selected values from an item into browser fields. your application or agent owns navigation, field selection, submission, and recovery.
+Fill from Vault is an integration path where your application or agent controls the login workflow. vaults store encrypted credential items. our `fill` api call writes selected values from an item into browser fields, without exposing secrets to your application or agent. your application or agent owns navigation, field selection, submission, and recovery.
start with the [end-user auth workflow cookbook](/browsers/use-vault-credentials-in-browser-agent) for an end-to-end example of secure collection, browser attachment, the `fill` operation, form submission, and cleanup.
@@ -18,9 +18,6 @@ KERNEL collects credential values from the user or accepts them from a trusted b
`fill` only writes stored values into fields you select. it doesn't discover fields, navigate, submit forms, verify authentication, monitor the session, or reauthenticate. your application or agent owns each of those steps.
-
- `fill` writes real values into the browser. page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them after filling.
-
## When to use it
diff --git a/auth/overview.mdx b/auth/overview.mdx
index a309a5d3..99893cd2 100644
--- a/auth/overview.mdx
+++ b/auth/overview.mdx
@@ -48,9 +48,6 @@ one common use case is an ai assistant doing work on behalf of an end user. with
one common use case is recurring website qa on a set of known sites. KERNEL handles the login flow and attempts eligible automatic recovery before the automation begins. the automation can start testing on websites without needing to login.
-
- with automatic recovery enabled, KERNEL can attempt to sign in again when a health check confirms that a session has expired. recovery isn't guaranteed. if the site requires an email or sms code, approval, or another user action, your application must bring the user back to complete a new login. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery details.
-
## Understand the security boundary