> ## Documentation Index
> Fetch the complete documentation index at: https://kernel.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Connection Configuration
> Shared options for managed auth connections, regardless of integration flow
Managed Auth connections use the same configuration whether you collect credentials through the [Hosted UI](/docs/auth/hosted-ui), the [React component](/docs/auth/react), or the [programmatic flow](/docs/auth/programmatic). These options apply to the initial login, every background health check, and each automatic reauthentication attempt.
## 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.
To opt out of credential saving, set `save_credentials: false` when creating the connection. See [Credentials](/docs/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` 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`.
```typescript TypeScript theme={null}
const auth = await kernel.auth.connections.create({
domain: 'example.com',
profile_name: 'my-profile',
health_checks: false,
auto_reauth: false,
});
```
```python Python theme={null}
auth = await kernel.auth.connections.create(
domain="example.com",
profile_name="my-profile",
health_checks=False,
auto_reauth=False,
)
```
```go Go theme={null}
auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
Domain: "example.com",
ProfileName: "my-profile",
HealthChecks: kernel.Bool(false),
AutoReauth: kernel.Bool(false),
},
})
if err != nil {
panic(err)
}
_ = auth
```
Both flags can be flipped on an existing connection with `auth.connections.update`; changes take effect immediately on the running connection.
Automatic reauthentication requires a previously successful login and saved credentials for the durable login fields. Setting `auto_reauth: true` permits Kernel to attempt it but doesn't guarantee the next login will succeed.
If Kernel can't complete an automatic attempt, the connection transitions to `NEEDS_AUTH` so you can start a new login.
## Custom Login URL
If the site's login page isn't at the default location, specify it when creating the connection:
```typescript TypeScript theme={null}
const auth = await kernel.auth.connections.create({
domain: 'example.com',
profile_name: 'my-profile',
login_url: 'https://example.com/auth/signin',
});
```
```python Python theme={null}
auth = await kernel.auth.connections.create(
domain="example.com",
profile_name="my-profile",
login_url="https://example.com/auth/signin",
)
```
```go Go theme={null}
auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
Domain: "example.com",
ProfileName: "my-profile",
LoginURL: kernel.String("https://example.com/auth/signin"),
},
})
if err != nil {
panic(err)
}
_ = auth
```
## SSO/OAuth Support
Managed Auth supports common "Sign in with Google/GitHub/Microsoft" flows. The user completes the OAuth flow with the provider, and Kernel saves the authenticated session to the profile. Automatic reauthentication depends on the provider's login requirements. See [Can this connection auto-reauth?](/docs/auth/connection-lifecycle#can-this-connection-auto-reauth) for how Kernel determines eligibility.
Common SSO provider domains are automatically allowed by default, including Google, Microsoft/Azure AD, Okta, Auth0, Apple, GitHub, Facebook, LinkedIn, Amazon Cognito, OneLogin, and Ping Identity. You don't need to add these to `allowed_domains`.
For custom or less common OAuth providers, add their domains to `allowed_domains`:
```typescript TypeScript theme={null}
const auth = await kernel.auth.connections.create({
domain: 'example.com',
profile_name: 'my-profile',
allowed_domains: ['sso.custom-provider.com'],
});
```
```python Python theme={null}
auth = await kernel.auth.connections.create(
domain="example.com",
profile_name="my-profile",
allowed_domains=["sso.custom-provider.com"],
)
```
```go Go theme={null}
auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
Domain: "example.com",
ProfileName: "my-profile",
AllowedDomains: []string{"sso.custom-provider.com"},
},
})
if err != nil {
panic(err)
}
_ = auth
```
## Custom Proxy
Pin the auth flow to a specific [proxy](/docs/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](/docs/proxies/isp)** and **[datacenter](/docs/proxies/datacenter)** proxies provide a stable exit IP within a single session, but Kernel does not guarantee the same IP across sessions. Sites with adaptive auth that trigger a step-up challenge (one-time code, device verification) when the client IP changes may flag the IP shift between the initial login and a subsequent health check or reauth.
* **[Residential](/docs/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)](/docs/proxies/custom)** proxies route through whatever you point them at, so this is the right pick if you need a truly static IP that persists across the initial login and every subsequent health check and reauth (e.g. an allowlisted egress your security team owns).
Create a proxy first, then attach it to the connection:
```typescript TypeScript theme={null}
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 theme={null}
proxy = kernel.proxies.create(type="isp")
auth = await kernel.auth.connections.create(
domain="example.com",
profile_name="my-profile",
proxy={"id": proxy.id},
)
```
```go Go theme={null}
proxy, err := client.Proxies.New(ctx, kernel.ProxyNewParams{
Type: kernel.ProxyNewParamsTypeIsp,
})
if err != nil {
panic(err)
}
auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
Domain: "example.com",
ProfileName: "my-profile",
Proxy: kernel.ManagedAuthCreateRequestProxyParam{
ID: kernel.String(proxy.ID),
},
},
})
if err != nil {
panic(err)
}
_ = auth
```
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, so the next health check or reauth uses the new proxy.
```typescript TypeScript theme={null}
await kernel.auth.connections.update(auth.id, {
proxy: { id: newProxy.id },
});
```
```python Python theme={null}
await kernel.auth.connections.update(
auth.id,
proxy={"id": new_proxy.id},
)
```
```go Go theme={null}
_, err := client.Auth.Connections.Update(ctx, auth.ID, kernel.AuthConnectionUpdateParams{
ManagedAuthUpdateRequest: kernel.ManagedAuthUpdateRequestParam{
Proxy: kernel.ManagedAuthUpdateRequestProxyParam{
ID: kernel.String(newProxy.ID),
},
},
})
if err != nil {
panic(err)
}
```
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 theme={null}
const login = await kernel.auth.connections.login(auth.id, {
proxy: { id: oneOffProxy.id },
});
```
```python Python theme={null}
login = await kernel.auth.connections.login(
auth.id,
proxy={"id": one_off_proxy.id},
)
```
```go Go theme={null}
login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{
Proxy: kernel.AuthConnectionLoginParamsProxy{
ID: kernel.String(oneOffProxy.ID),
},
})
if err != nil {
panic(err)
}
_ = login
```
## Record Sessions for Debugging
Set `record_session: true` to capture a [replay](/docs/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 theme={null}
const auth = await kernel.auth.connections.create({
domain: 'example.com',
profile_name: 'my-profile',
record_session: true,
});
```
```python Python theme={null}
auth = await kernel.auth.connections.create(
domain="example.com",
profile_name="my-profile",
record_session=True,
)
```
```go Go theme={null}
auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
Domain: "example.com",
ProfileName: "my-profile",
RecordSession: kernel.Bool(true),
},
})
if err != nil {
panic(err)
}
_ = auth
```
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 theme={null}
const login = await kernel.auth.connections.login(auth.id, {
record_session: true,
});
```
```python Python theme={null}
login = await kernel.auth.connections.login(
auth.id,
record_session=True,
)
```
```go Go theme={null}
login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{
RecordSession: kernel.Bool(true),
})
if err != nil {
panic(err)
}
_ = login
```
Managed auth recordings are subject to the same retention rules as other session replay recordings. 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 theme={null}
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 theme={null}
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
```
```go Go theme={null}
managedAuth, err := client.Auth.Connections.Get(ctx, auth.ID)
if err != nil {
panic(err)
}
if managedAuth.PostLoginURL != "" {
_, err := client.Browsers.Playwright.Execute(ctx, browser.SessionID, kernel.BrowserPlaywrightExecuteParams{
Code: fmt.Sprintf(`await page.goto(%q);`, managedAuth.PostLoginURL),
})
if err != nil {
panic(err)
}
// 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) |
| `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 |
| `save_credentials` | Whether to save credentials on successful login |
| `record_session` | Record a [replay](/docs/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 on the next health check or reauth |
Only the fields you include are updated—everything else stays the same. Changes to `health_check_interval`, `health_checks`, `auto_reauth`, and `proxy` take effect immediately on the running connection.
```typescript TypeScript theme={null}
await kernel.auth.connections.update(auth.id, {
login_url: 'https://example.com/new-login',
health_check_interval: 1800,
save_credentials: true,
});
```
```python Python theme={null}
await kernel.auth.connections.update(
auth.id,
login_url="https://example.com/new-login",
health_check_interval=1800,
save_credentials=True,
)
```
```go Go theme={null}
_, err := client.Auth.Connections.Update(ctx, auth.ID, kernel.AuthConnectionUpdateParams{
ManagedAuthUpdateRequest: kernel.ManagedAuthUpdateRequestParam{
LoginURL: kernel.String("https://example.com/new-login"),
HealthCheckInterval: kernel.Int(1800),
SaveCredentials: kernel.Bool(true),
},
})
if err != nil {
panic(err)
}
```