From 607f0981a2adc2d9c30955557d15d43b45aced27 Mon Sep 17 00:00:00 2001
From: masnwilliams <43387599+masnwilliams@users.noreply.github.com>
Date: Wed, 13 May 2026 16:05:44 +0000
Subject: [PATCH 1/5] docs: document custom proxy for managed auth connections
Add a Custom Proxy section to the hosted UI page covering attach on
create, swap on update, and per-login override. Sharpen the proxy row
in the programmatic update table with a link to the new section.
---
auth/hosted-ui.mdx | 66 +++++++++++++++++++++++++++++++++++++++++++
auth/programmatic.mdx | 2 +-
2 files changed, 67 insertions(+), 1 deletion(-)
diff --git a/auth/hosted-ui.mdx b/auth/hosted-ui.mdx
index 20d207e..2ef289c 100644
--- a/auth/hosted-ui.mdx
+++ b/auth/hosted-ui.mdx
@@ -262,6 +262,72 @@ auth = await kernel.auth.connections.create(
```
+### Custom Proxy
+
+Pin the auth flow to a specific [proxy](/proxies/overview) so logins, health checks, and automatic re-authentications all egress through the same IP. This is useful for sites that allowlist IPs, geo-pin sessions, or treat IP changes as a fraud signal.
+
+Create a proxy first, then attach it to the connection:
+
+
+```typescript TypeScript
+const proxy = await kernel.proxies.create({ type: 'isp' });
+
+const auth = await kernel.auth.connections.create({
+ domain: 'example.com',
+ profile_name: 'my-profile',
+ proxy: { id: proxy.id },
+});
+```
+
+```python Python
+proxy = kernel.proxies.create(type="isp")
+
+auth = await kernel.auth.connections.create(
+ domain="example.com",
+ profile_name="my-profile",
+ proxy={"id": proxy.id},
+)
+```
+
+
+You can also reference a proxy by `name` instead of `id`. The proxy must belong to the same org and project as the connection.
+
+Once attached, every browser the connection spins up — the initial login, every background health check, and every automatic re-auth — runs through that proxy.
+
+You can swap the proxy on an existing connection with `auth.connections.update`; the change takes effect immediately on the running connection workflow.
+
+
+```typescript TypeScript
+await kernel.auth.connections.update(auth.id, {
+ proxy: { id: newProxy.id },
+});
+```
+
+```python Python
+await kernel.auth.connections.update(
+ auth.id,
+ proxy={"id": new_proxy.id},
+)
+```
+
+
+You can also override the connection's proxy for a single login by passing `proxy` on `.login()` — useful when you want to try a one-off egress without changing the connection-wide default (which would also affect subsequent health checks and reauths).
+
+
+```typescript TypeScript
+const login = await kernel.auth.connections.login(auth.id, {
+ proxy: { id: oneOffProxy.id },
+});
+```
+
+```python Python
+login = await kernel.auth.connections.login(
+ auth.id,
+ proxy={"id": one_off_proxy.id},
+)
+```
+
+
### Updating a Connection
After creating a connection, you can update its configuration using `auth.connections.update`:
diff --git a/auth/programmatic.mdx b/auth/programmatic.mdx
index 67998e6..483d535 100644
--- a/auth/programmatic.mdx
+++ b/auth/programmatic.mdx
@@ -462,7 +462,7 @@ After creating a connection, you can update its configuration with `PATCH /auth/
| `health_check_interval` | Seconds between health checks (minimum varies by plan) |
| `save_credentials` | Whether to save credentials on successful login |
| `record_session` | Record a [replay](/browsers/replays) of every auth browser session for this connection (logins, health checks, and reauths) |
-| `proxy` | Proxy configuration for login sessions |
+| `proxy` | Pin login, health-check, and reauth sessions to a [proxy](/auth/hosted-ui#custom-proxy). Takes effect immediately on the running workflow |
Only the fields you include are updated—everything else stays the same.
From f0439bd299b24948b3405934994e01218c98a4da Mon Sep 17 00:00:00 2001
From: masnwilliams <43387599+masnwilliams@users.noreply.github.com>
Date: Wed, 13 May 2026 16:29:52 +0000
Subject: [PATCH 2/5] docs: extract shared connection configuration into its
own page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Connection-level options — credentials, custom login URL, SSO/OAuth,
custom proxy, session recording, post-login URL, and updates — apply
equally to hosted UI, React, and programmatic flows. Move them into
auth/configuration.mdx and link from each integration page so the
options aren't buried under one flow.
---
auth/configuration.mdx | 225 +++++++++++++++++++++++++++++++++++++++++
auth/faq.mdx | 2 +-
auth/hosted-ui.mdx | 213 +-------------------------------------
auth/programmatic.mdx | 35 +------
docs.json | 1 +
5 files changed, 231 insertions(+), 245 deletions(-)
create mode 100644 auth/configuration.mdx
diff --git a/auth/configuration.mdx b/auth/configuration.mdx
new file mode 100644
index 0000000..e1bbad8
--- /dev/null
+++ b/auth/configuration.mdx
@@ -0,0 +1,225 @@
+---
+title: "Connection Configuration"
+description: "Shared options for managed auth connections, regardless of integration flow"
+---
+
+Managed Auth Connections are configured the same way regardless of how you collect credentials — via [Hosted UI](/auth/hosted-ui), the [React component](/auth/react), or the [programmatic flow](/auth/programmatic). The options below live on the connection itself and apply to the initial login, every background health check, and every automatic re-authentication.
+
+## Credentials and Auto-Reauth
+
+Credentials are saved after every successful login, enabling automatic re-authentication when the session expires. One-time codes (TOTP, SMS, etc.) are not saved.
+
+To opt out of credential saving, set `save_credentials: false` when creating the connection. See [Credentials](/auth/credentials) for more on automated authentication.
+
+## Custom Login URL
+
+If the site's login page isn't at the default location, specify it when creating the connection:
+
+
+```typescript TypeScript
+const auth = await kernel.auth.connections.create({
+ domain: 'example.com',
+ profile_name: 'my-profile',
+ login_url: 'https://example.com/auth/signin',
+});
+```
+
+```python Python
+auth = await kernel.auth.connections.create(
+ domain="example.com",
+ profile_name="my-profile",
+ login_url="https://example.com/auth/signin",
+)
+```
+
+
+## SSO/OAuth Support
+
+Sites with "Sign in with Google/GitHub/Microsoft" are supported. The user completes the OAuth flow with the provider, and the authenticated session is automatically saved to the Kernel profile.
+
+Common SSO provider domains are automatically allowed by default, including Google, Microsoft/Azure AD, Okta, Auth0, Apple, GitHub, Facebook, LinkedIn, Amazon Cognito, OneLogin, and Ping Identity. You don't need to add these to `allowed_domains`.
+
+For custom or less common OAuth providers, add their domains to `allowed_domains`:
+
+
+```typescript TypeScript
+const auth = await kernel.auth.connections.create({
+ domain: 'example.com',
+ profile_name: 'my-profile',
+ allowed_domains: ['sso.custom-provider.com'],
+});
+```
+
+```python Python
+auth = await kernel.auth.connections.create(
+ domain="example.com",
+ profile_name="my-profile",
+ allowed_domains=["sso.custom-provider.com"],
+)
+```
+
+
+## Custom Proxy
+
+Pin the auth flow to a specific [proxy](/proxies/overview) so logins, health checks, and automatic re-authentications all egress through the same IP. This is useful for sites that allowlist IPs, geo-pin sessions, or treat IP changes as a fraud signal.
+
+Create a proxy first, then attach it to the connection:
+
+
+```typescript TypeScript
+const proxy = await kernel.proxies.create({ type: 'isp' });
+
+const auth = await kernel.auth.connections.create({
+ domain: 'example.com',
+ profile_name: 'my-profile',
+ proxy: { id: proxy.id },
+});
+```
+
+```python Python
+proxy = kernel.proxies.create(type="isp")
+
+auth = await kernel.auth.connections.create(
+ domain="example.com",
+ profile_name="my-profile",
+ proxy={"id": proxy.id},
+)
+```
+
+
+You can also reference a proxy by `name` instead of `id`. The proxy must belong to the same org and project as the connection.
+
+Once attached, every browser the connection spins up — the initial login, every background health check, and every automatic re-auth — runs through that proxy.
+
+You can swap the proxy on an existing connection with `auth.connections.update`; the change takes effect immediately on the running connection workflow.
+
+
+```typescript TypeScript
+await kernel.auth.connections.update(auth.id, {
+ proxy: { id: newProxy.id },
+});
+```
+
+```python Python
+await kernel.auth.connections.update(
+ auth.id,
+ proxy={"id": new_proxy.id},
+)
+```
+
+
+You can also override the connection's proxy for a single login by passing `proxy` on `.login()` — useful when you want to try a one-off egress without changing the connection-wide default (which would also affect subsequent health checks and reauths).
+
+
+```typescript TypeScript
+const login = await kernel.auth.connections.login(auth.id, {
+ proxy: { id: oneOffProxy.id },
+});
+```
+
+```python Python
+login = await kernel.auth.connections.login(
+ auth.id,
+ proxy={"id": one_off_proxy.id},
+)
+```
+
+
+## Record Sessions for Debugging
+
+Set `record_session: true` to capture a [replay](/browsers/replays) of every browser session tied to the connection — initial logins, background health checks, and automatic re-authentications. Recordings start automatically when each auth browser is created and stop when it's destroyed — no explicit stop call needed.
+
+
+```typescript TypeScript
+const auth = await kernel.auth.connections.create({
+ domain: 'example.com',
+ profile_name: 'my-profile',
+ record_session: true,
+});
+```
+
+```python Python
+auth = await kernel.auth.connections.create(
+ domain="example.com",
+ profile_name="my-profile",
+ record_session=True,
+)
+```
+
+
+You can also override the connection default for a single login by passing `record_session` on `.login()` — useful for one-off debugging on a specific login attempt without flipping the connection-wide flag (which would also record subsequent health checks and reauths).
+
+
+```typescript TypeScript
+const login = await kernel.auth.connections.login(auth.id, {
+ record_session: true,
+});
+```
+
+```python Python
+login = await kernel.auth.connections.login(
+ auth.id,
+ record_session=True,
+)
+```
+
+
+Recordings count toward your replay storage like any other browser replay. Each managed auth session row stores its own `replay_id` for the recording captured during that session.
+
+## Post-Login URL
+
+After successful authentication, `post_login_url` will be set to the page where the login landed. Use this to start your automation from the right place:
+
+
+```typescript TypeScript
+const managedAuth = await kernel.auth.connections.retrieve(auth.id);
+
+if (managedAuth.post_login_url) {
+ await page.goto(managedAuth.post_login_url);
+ // Start automation from the dashboard/home page
+}
+```
+
+```python Python
+managed_auth = await kernel.auth.connections.retrieve(auth.id)
+
+if managed_auth.post_login_url:
+ await page.goto(managed_auth.post_login_url)
+ # Start automation from the dashboard/home page
+```
+
+
+## Updating a Connection
+
+After creating a connection, you can update its configuration with `auth.connections.update`:
+
+| Field | Description |
+|-------|-------------|
+| `login_url` | Override the login page URL |
+| `credential` | Update the linked credential |
+| `allowed_domains` | Update allowed redirect domains |
+| `health_check_interval` | Seconds between health checks (minimum varies by plan) |
+| `save_credentials` | Whether to save credentials on successful login |
+| `record_session` | Record a [replay](/browsers/replays) of every auth browser session for this connection (logins, health checks, and reauths) |
+| `proxy` | Pin login, health-check, and reauth sessions to a proxy. Takes effect immediately on the running workflow |
+
+Only the fields you include are updated—everything else stays the same. Changes to `health_check_interval` and `proxy` take effect immediately on the running connection workflow.
+
+
+```typescript TypeScript
+await kernel.auth.connections.update(auth.id, {
+ login_url: 'https://example.com/new-login',
+ health_check_interval: 1800,
+ save_credentials: true,
+});
+```
+
+```python Python
+await kernel.auth.connections.update(
+ auth.id,
+ login_url="https://example.com/new-login",
+ health_check_interval=1800,
+ save_credentials=True,
+)
+```
+
diff --git a/auth/faq.mdx b/auth/faq.mdx
index 405c615..537230c 100644
--- a/auth/faq.mdx
+++ b/auth/faq.mdx
@@ -106,7 +106,7 @@ Managed Auth handles login and authentication flows end-to-end: entering credent
Go to the **Browser Sessions** tab in the Kernel dashboard to watch what the managed auth session is doing in real time. Each auth login runs in a browser session with a live view, so you can see exactly where the flow is getting stuck. This is useful for diagnosing login flow problems or understanding why a session isn't staying authenticated.
-For flakes that only show up intermittently or are hard to reproduce live, set `record_session: true` on the connection to capture a [replay](/browsers/replays) of every auth browser session — logins, periodic health checks, and automatic reauths. To record only a single login attempt without recording subsequent health checks and reauths, pass `record_session: true` on `.login()` instead. Recordings start automatically when each auth browser is created and stop when it's destroyed, the `replay_id` is persisted on each session, and recordings count toward your normal replay storage. See the [Hosted UI guide](/auth/hosted-ui#record-sessions-for-debugging) for examples.
+For flakes that only show up intermittently or are hard to reproduce live, set `record_session: true` on the connection to capture a [replay](/browsers/replays) of every auth browser session — logins, periodic health checks, and automatic reauths. To record only a single login attempt without recording subsequent health checks and reauths, pass `record_session: true` on `.login()` instead. Recordings start automatically when each auth browser is created and stop when it's destroyed, the `replay_id` is persisted on each session, and recordings count toward your normal replay storage. See [Connection Configuration](/auth/configuration#record-sessions-for-debugging) for examples.
## Can I attach multiple auth connections to one profile?
diff --git a/auth/hosted-ui.mdx b/auth/hosted-ui.mdx
index 2ef289c..1fb150b 100644
--- a/auth/hosted-ui.mdx
+++ b/auth/hosted-ui.mdx
@@ -204,215 +204,6 @@ if state.status == "AUTHENTICATED":
```
-## Adding Features
+## Connection Configuration
-The basic flow above gets you started. Add these features as needed:
-
-### Credentials and Auto-Reauth
-
-Credentials are saved after every successful login, enabling automatic re-authentication when the session expires. One-time codes (TOTP, SMS, etc.) are not saved.
-
-To opt out of credential saving, set `save_credentials: false` when creating the connection. See [Credentials](/auth/credentials) for more on automated authentication.
-
-### Custom Login URL
-
-If the site's login page isn't at the default location, specify it when creating the connection:
-
-
-```typescript TypeScript
-const auth = await kernel.auth.connections.create({
- domain: 'example.com',
- profile_name: 'my-profile',
- login_url: 'https://example.com/auth/signin',
-});
-```
-
-```python Python
-auth = await kernel.auth.connections.create(
- domain="example.com",
- profile_name="my-profile",
- login_url="https://example.com/auth/signin",
-)
-```
-
-
-### SSO/OAuth Support
-
-Sites with "Sign in with Google/GitHub/Microsoft" are supported. The user completes the OAuth flow with the provider, and the authenticated session is automatically saved to the Kernel profile.
-
-Common SSO provider domains are automatically allowed by default, including Google, Microsoft/Azure AD, Okta, Auth0, Apple, GitHub, Facebook, LinkedIn, Amazon Cognito, OneLogin, and Ping Identity. You don't need to add these to `allowed_domains`.
-
-For custom or less common OAuth providers, add their domains to `allowed_domains`:
-
-
-```typescript TypeScript
-const auth = await kernel.auth.connections.create({
- domain: 'example.com',
- profile_name: 'my-profile',
- allowed_domains: ['sso.custom-provider.com'],
-});
-```
-
-```python Python
-auth = await kernel.auth.connections.create(
- domain="example.com",
- profile_name="my-profile",
- allowed_domains=["sso.custom-provider.com"],
-)
-```
-
-
-### Custom Proxy
-
-Pin the auth flow to a specific [proxy](/proxies/overview) so logins, health checks, and automatic re-authentications all egress through the same IP. This is useful for sites that allowlist IPs, geo-pin sessions, or treat IP changes as a fraud signal.
-
-Create a proxy first, then attach it to the connection:
-
-
-```typescript TypeScript
-const proxy = await kernel.proxies.create({ type: 'isp' });
-
-const auth = await kernel.auth.connections.create({
- domain: 'example.com',
- profile_name: 'my-profile',
- proxy: { id: proxy.id },
-});
-```
-
-```python Python
-proxy = kernel.proxies.create(type="isp")
-
-auth = await kernel.auth.connections.create(
- domain="example.com",
- profile_name="my-profile",
- proxy={"id": proxy.id},
-)
-```
-
-
-You can also reference a proxy by `name` instead of `id`. The proxy must belong to the same org and project as the connection.
-
-Once attached, every browser the connection spins up — the initial login, every background health check, and every automatic re-auth — runs through that proxy.
-
-You can swap the proxy on an existing connection with `auth.connections.update`; the change takes effect immediately on the running connection workflow.
-
-
-```typescript TypeScript
-await kernel.auth.connections.update(auth.id, {
- proxy: { id: newProxy.id },
-});
-```
-
-```python Python
-await kernel.auth.connections.update(
- auth.id,
- proxy={"id": new_proxy.id},
-)
-```
-
-
-You can also override the connection's proxy for a single login by passing `proxy` on `.login()` — useful when you want to try a one-off egress without changing the connection-wide default (which would also affect subsequent health checks and reauths).
-
-
-```typescript TypeScript
-const login = await kernel.auth.connections.login(auth.id, {
- proxy: { id: oneOffProxy.id },
-});
-```
-
-```python Python
-login = await kernel.auth.connections.login(
- auth.id,
- proxy={"id": one_off_proxy.id},
-)
-```
-
-
-### Updating a Connection
-
-After creating a connection, you can update its configuration using `auth.connections.update`:
-
-
-```typescript TypeScript
-await kernel.auth.connections.update(auth.id, {
- login_url: 'https://example.com/new-login',
- health_check_interval: 1800,
- save_credentials: true,
-});
-```
-
-```python Python
-await kernel.auth.connections.update(
- auth.id,
- login_url="https://example.com/new-login",
- health_check_interval=1800,
- save_credentials=True,
-)
-```
-
-
-You can update `login_url`, `credential`, `allowed_domains`, `health_check_interval`, `save_credentials`, `record_session`, and `proxy`. Only the fields you provide will be changed. Changes to `health_check_interval` and `proxy` take effect immediately on the running connection workflow.
-
-### Record Sessions for Debugging
-
-Set `record_session: true` to capture a [replay](/browsers/replays) of every browser session tied to the connection — initial logins, background health checks, and automatic re-authentications. Recordings start automatically when each auth browser is created and stop when it's destroyed — no explicit stop call needed.
-
-
-```typescript TypeScript
-const auth = await kernel.auth.connections.create({
- domain: 'example.com',
- profile_name: 'my-profile',
- record_session: true,
-});
-```
-
-```python Python
-auth = await kernel.auth.connections.create(
- domain="example.com",
- profile_name="my-profile",
- record_session=True,
-)
-```
-
-
-You can also override the connection default for a single login by passing `record_session` on `.login()` — useful for one-off debugging on a specific login attempt without flipping the connection-wide flag (which would also record subsequent health checks and reauths).
-
-
-```typescript TypeScript
-const login = await kernel.auth.connections.login(auth.id, {
- record_session: true,
-});
-```
-
-```python Python
-login = await kernel.auth.connections.login(
- auth.id,
- record_session=True,
-)
-```
-
-
-Recordings count toward your replay storage like any other browser replay. Each managed auth session row stores its own `replay_id` for the recording captured during that session.
-
-### Post-Login URL
-
-After successful authentication, `post_login_url` will be set to the page where the login landed. Use this start your automation from the right place:
-
-
-```typescript TypeScript
-const managedAuth = await kernel.auth.connections.retrieve(auth.id);
-
-if (managedAuth.post_login_url) {
- await page.goto(managedAuth.post_login_url);
- // Start automation from the dashboard/home page
-}
-```
-
-```python Python
-managed_auth = await kernel.auth.connections.retrieve(auth.id)
-
-if managed_auth.post_login_url:
- await page.goto(managed_auth.post_login_url)
- # Start automation from the dashboard/home page
-```
-
+Connection-level options — custom login URL, SSO/OAuth, custom proxy, session recording, post-login URL, and updates — apply equally to all integration flows and are documented in [Connection Configuration](/auth/configuration).
diff --git a/auth/programmatic.mdx b/auth/programmatic.mdx
index 483d535..5161fff 100644
--- a/auth/programmatic.mdx
+++ b/auth/programmatic.mdx
@@ -450,40 +450,9 @@ The `status` field indicates the overall connection state:
| `AUTHENTICATED` | Profile is logged in and ready to use |
| `NEEDS_AUTH` | Profile needs authentication |
-## Updating Connections
+## Connection Configuration
-After creating a connection, you can update its configuration with `PATCH /auth/connections/{id}`:
-
-| Field | Description |
-|-------|-------------|
-| `login_url` | Override the login page URL |
-| `credential` | Update the linked credential |
-| `allowed_domains` | Update allowed redirect domains |
-| `health_check_interval` | Seconds between health checks (minimum varies by plan) |
-| `save_credentials` | Whether to save credentials on successful login |
-| `record_session` | Record a [replay](/browsers/replays) of every auth browser session for this connection (logins, health checks, and reauths) |
-| `proxy` | Pin login, health-check, and reauth sessions to a [proxy](/auth/hosted-ui#custom-proxy). Takes effect immediately on the running workflow |
-
-Only the fields you include are updated—everything else stays the same.
-
-
-```typescript TypeScript
-await kernel.auth.connections.update(auth.id, {
- login_url: 'https://example.com/login',
- health_check_interval: 1800,
- save_credentials: true,
-});
-```
-
-```python Python
-await kernel.auth.connections.update(
- auth.id,
- login_url="https://example.com/login",
- health_check_interval=1800,
- save_credentials=True,
-)
-```
-
+Connection-level options — custom login URL, SSO/OAuth, custom proxy, session recording, post-login URL, and updates — apply equally to all integration flows and are documented in [Connection Configuration](/auth/configuration).
## Real-Time Updates with SSE
diff --git a/docs.json b/docs.json
index f68ac13..640fc3d 100644
--- a/docs.json
+++ b/docs.json
@@ -103,6 +103,7 @@
"auth/programmatic"
]
},
+ "auth/configuration",
"auth/credentials",
"auth/profiles",
"auth/faq"
From 8961470d24b45b0af8a015364c454b847c283594 Mon Sep 17 00:00:00 2001
From: masnwilliams <43387599+masnwilliams@users.noreply.github.com>
Date: Wed, 13 May 2026 16:51:25 +0000
Subject: [PATCH 3/5] docs: link react auth flow to shared connection
configuration page
---
auth/react.mdx | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/auth/react.mdx b/auth/react.mdx
index 329b8d4..bd295d5 100644
--- a/auth/react.mdx
+++ b/auth/react.mdx
@@ -242,6 +242,10 @@ import {
Wrap them in `` and `` to inherit the same styling/localization plumbing as the all-in-one component.
+## Connection Configuration
+
+Connection-level options — custom login URL, SSO/OAuth, custom proxy, session recording, post-login URL, and updates — are set on `auth.connections.create` (or later via `auth.connections.update`) and apply equally regardless of which integration flow you use. See [Connection Configuration](/auth/configuration).
+
## Reference integration
A full reference integration — Next.js shell, rewrites, end-to-end flow — lives at [`kernel/managed-auth-hosted-ui`](https://github.com/kernel/managed-auth-hosted-ui). It powers Kernel's own hosted login page and is a copy-pasteable starting point for embedding the component in your own app.
From 4f5fe9597d20ec00963662e55478cba2022deb01 Mon Sep 17 00:00:00 2001
From: masnwilliams <43387599+masnwilliams@users.noreply.github.com>
Date: Wed, 13 May 2026 17:24:01 +0000
Subject: [PATCH 4/5] docs: clarify exit IP stability for proxy on managed auth
connections
ISP/datacenter are static; residential rotates per connection; custom
(BYO) is the only way to guarantee a fully customer-controlled static
IP. Reflect this in the Custom Proxy section instead of implying all
proxies pin to the same IP.
---
auth/configuration.mdx | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/auth/configuration.mdx b/auth/configuration.mdx
index e1bbad8..217f76d 100644
--- a/auth/configuration.mdx
+++ b/auth/configuration.mdx
@@ -61,7 +61,13 @@ auth = await kernel.auth.connections.create(
## Custom Proxy
-Pin the auth flow to a specific [proxy](/proxies/overview) so logins, health checks, and automatic re-authentications all egress through the same IP. This is useful for sites that allowlist IPs, geo-pin sessions, or treat IP changes as a fraud signal.
+Pin the auth flow to a specific [proxy](/proxies/overview) so logins, health checks, and automatic re-authentications all egress through that proxy. This is useful for sites that allowlist IPs, geo-pin sessions, or treat IP changes as a fraud signal.
+
+How stable the exit IP is depends on the proxy type:
+
+- **[ISP](/proxies/isp)** and **[datacenter](/proxies/datacenter)** proxies provide a static exit IP that stays consistent across all connections.
+- **[Residential](/proxies/residential)** proxies rotate IPs per connection — use them when you need legitimacy from a real ISP pool but can tolerate IP changes.
+- **[Custom (BYO)](/proxies/custom)** proxies route through whatever you point them at, so this is the right pick if you need a truly static IP under your own control (e.g. an allowlisted egress your security team owns).
Create a proxy first, then attach it to the connection:
From 8d1467642693c64fc66794c683c4b2db28310482 Mon Sep 17 00:00:00 2001
From: masnwilliams <43387599+masnwilliams@users.noreply.github.com>
Date: Wed, 13 May 2026 17:24:36 +0000
Subject: [PATCH 5/5] docs: simplify session recording description for managed
auth
Drop the start/stop lifecycle detail and just say the entire browser
session is recorded.
---
auth/configuration.mdx | 2 +-
auth/faq.mdx | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/auth/configuration.mdx b/auth/configuration.mdx
index 217f76d..1f371db 100644
--- a/auth/configuration.mdx
+++ b/auth/configuration.mdx
@@ -133,7 +133,7 @@ login = await kernel.auth.connections.login(
## Record Sessions for Debugging
-Set `record_session: true` to capture a [replay](/browsers/replays) of every browser session tied to the connection — initial logins, background health checks, and automatic re-authentications. Recordings start automatically when each auth browser is created and stop when it's destroyed — no explicit stop call needed.
+Set `record_session: true` to capture a [replay](/browsers/replays) of every browser session tied to the connection — initial logins, background health checks, and automatic re-authentications. The entire browser session is recorded.
```typescript TypeScript
diff --git a/auth/faq.mdx b/auth/faq.mdx
index 537230c..fde51b6 100644
--- a/auth/faq.mdx
+++ b/auth/faq.mdx
@@ -106,7 +106,7 @@ Managed Auth handles login and authentication flows end-to-end: entering credent
Go to the **Browser Sessions** tab in the Kernel dashboard to watch what the managed auth session is doing in real time. Each auth login runs in a browser session with a live view, so you can see exactly where the flow is getting stuck. This is useful for diagnosing login flow problems or understanding why a session isn't staying authenticated.
-For flakes that only show up intermittently or are hard to reproduce live, set `record_session: true` on the connection to capture a [replay](/browsers/replays) of every auth browser session — logins, periodic health checks, and automatic reauths. To record only a single login attempt without recording subsequent health checks and reauths, pass `record_session: true` on `.login()` instead. Recordings start automatically when each auth browser is created and stop when it's destroyed, the `replay_id` is persisted on each session, and recordings count toward your normal replay storage. See [Connection Configuration](/auth/configuration#record-sessions-for-debugging) for examples.
+For flakes that only show up intermittently or are hard to reproduce live, set `record_session: true` on the connection to capture a [replay](/browsers/replays) of every auth browser session — logins, periodic health checks, and automatic reauths. To record only a single login attempt without recording subsequent health checks and reauths, pass `record_session: true` on `.login()` instead. The entire browser session is recorded, the `replay_id` is persisted on each session, and recordings count toward your normal replay storage. See [Connection Configuration](/auth/configuration#record-sessions-for-debugging) for examples.
## Can I attach multiple auth connections to one profile?