> ## Documentation Index
> Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-ia-how-it-works.mintlify.site/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](/auth/hosted-ui), the [React component](/auth/react), or the [programmatic flow](/auth/programmatic). These options apply to the initial login, every background health check, and each automatic reauthentication attempt.
## Credentials and auto-reauth
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.
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)
* **Pre-store in Kernel** — Create credentials before login for supported headless authentication flows
* **Connect 1Password** — Use credentials from your existing 1Password vaults
Connect your 1Password vaults to automatically use existing credentials with Managed Auth. Credentials are automatically matched by domain.
### Save credentials during login
By default, Kernel saves durable credential fields entered during login so they can be used for eligible reauthentication attempts. No extra parameters are needed:
```typescript TypeScript theme={null}
const login = await kernel.auth.connections.login(auth.id);
```
```python Python theme={null}
login = await kernel.auth.connections.login(auth.id)
```
```go Go theme={null}
login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{})
if err != nil {
panic(err)
}
_ = login
```
Once saved, the browser profile reuses its authenticated session until the site expires it. For supported credential-based flows, Kernel can then reauthenticate with the stored values. Credentials are updated after every successful login. Submitted one-time codes aren't saved; Kernel generates TOTP codes from a stored `totp_secret`.
To opt out of credential saving, set `save_credentials: false` when creating the connection:
```typescript TypeScript theme={null}
const auth = await kernel.auth.connections.create({
domain: 'example.com',
profile_name: 'my-profile',
save_credentials: false,
});
```
```python Python theme={null}
auth = await kernel.auth.connections.create(
domain="example.com",
profile_name="my-profile",
save_credentials=False,
)
```
```go Go theme={null}
auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
Domain: "example.com",
ProfileName: "my-profile",
SaveCredentials: kernel.Bool(false),
},
})
if err != nil {
panic(err)
}
_ = auth
```
### Pre-store credentials
For credential-based flows that you want to run without user input, create credentials upfront:
```typescript TypeScript theme={null}
const credential = await kernel.credentials.create({
name: 'my-netflix-login',
domain: 'netflix.com',
values: {
email: 'user@netflix.com',
password: 'secretpassword123',
},
});
```
```python Python theme={null}
credential = await kernel.credentials.create(
name="my-netflix-login",
domain="netflix.com",
values={
"email": "user@netflix.com",
"password": "secretpassword123",
},
)
```
```go Go theme={null}
credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{
CreateCredentialRequest: kernel.CreateCredentialRequestParam{
Name: "my-netflix-login",
Domain: "netflix.com",
Values: map[string]string{
"email": "user@netflix.com",
"password": "secretpassword123",
},
},
})
if err != nil {
panic(err)
}
_ = credential
```
Then link the credential when creating a connection:
```typescript TypeScript theme={null}
const auth = await kernel.auth.connections.create({
domain: 'netflix.com',
profile_name: 'my-profile',
credential: { name: credential.name },
});
// Start login with stored credentials
const login = await kernel.auth.connections.login(auth.id);
```
```python Python theme={null}
auth = await kernel.auth.connections.create(
domain="netflix.com",
profile_name="my-profile",
credential={"name": credential.name},
)
# Start login with stored credentials
login = await kernel.auth.connections.login(auth.id)
```
```go Go theme={null}
auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
Domain: "netflix.com",
ProfileName: "my-profile",
Credential: kernel.ManagedAuthCreateRequestCredentialParam{
Name: kernel.String(credential.Name),
},
},
})
if err != nil {
panic(err)
}
// Start login with stored credentials
login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{})
if err != nil {
panic(err)
}
_ = login
```
#### 2FA with TOTP
For sites with authenticator app 2FA, include `totp_secret` so KERNEL can generate a fresh code during automatic login and reauthentication. Supply a base32 secret of 16–128 characters or an `otpauth://totp/` provisioning URI. The default is SHA1, 6 digits, and a 30-second period. If the authenticator uses different settings, provide `totp_algorithm` (`SHA1`, `SHA256`, or `SHA512`), `totp_digits` (6–9), and `totp_period` (15–300 seconds):
```typescript TypeScript theme={null}
const credential = await kernel.credentials.create({
name: 'my-login',
domain: 'github.com',
values: {
username: 'my-username',
password: 'my-password',
},
totp_secret: 'JBSWY3DPEHPK3PXP',
totp_algorithm: 'SHA512',
totp_digits: 8,
totp_period: 60,
});
```
```python Python theme={null}
credential = await kernel.credentials.create(
name="my-login",
domain="github.com",
values={
"username": "my-username",
"password": "my-password",
},
totp_secret="JBSWY3DPEHPK3PXP",
totp_algorithm="SHA512",
totp_digits=8,
totp_period=60,
)
```
```go Go theme={null}
credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{
CreateCredentialRequest: kernel.CreateCredentialRequestParam{
Name: "my-login",
Domain: "github.com",
Values: map[string]string{
"username": "my-username",
"password": "my-password",
},
TotpSecret: kernel.String("JBSWY3DPEHPK3PXP"),
TotpAlgorithm: kernel.CreateCredentialRequestTotpAlgorithmSha512,
TotpDigits: kernel.Int(8),
TotpPeriod: kernel.Int(60),
},
})
if err != nil {
panic(err)
}
_ = credential
```
The examples use typed fields available in TypeScript, Python, and Go SDK v0.116.0 or later. You can also pass an `otpauth://totp/` provisioning URI as `totp_secret`.
* URI parameters override explicit settings. If a parameter is missing, the API uses its explicit field, then the default.
* Replacing a URI resets omitted settings to defaults. Rotating a raw secret preserves stored settings unless you send new values.
* The API stores only the normalized seed, never the URI label or issuer.
* A code's length follows `totp_digits`; don't assume six digits when reading `totp_code` or calling `totpCode()`.
#### SSO / OAuth
For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` so Kernel can select the matching SSO route. Automatic completion depends on the provider's login requirements.
Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are allowed by default, so you don't need to add them to `allowed_domains`:
```typescript TypeScript theme={null}
const credential = await kernel.credentials.create({
name: 'my-google-login',
domain: 'accounts.google.com',
sso_provider: 'google',
values: {
email: 'user@gmail.com',
password: 'password',
},
});
const auth = await kernel.auth.connections.create({
domain: 'target-site.com',
profile_name: 'my-profile',
credential: { name: credential.name },
});
```
```python Python theme={null}
credential = await kernel.credentials.create(
name="my-google-login",
domain="accounts.google.com",
sso_provider="google",
values={
"email": "user@gmail.com",
"password": "password",
},
)
auth = await kernel.auth.connections.create(
domain="target-site.com",
profile_name="my-profile",
credential={"name": credential.name},
)
```
```go Go theme={null}
credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{
CreateCredentialRequest: kernel.CreateCredentialRequestParam{
Name: "my-google-login",
Domain: "accounts.google.com",
SSOProvider: kernel.String("google"),
Values: map[string]string{
"email": "user@gmail.com",
"password": "password",
},
},
})
if err != nil {
panic(err)
}
auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
Domain: "target-site.com",
ProfileName: "my-profile",
Credential: kernel.ManagedAuthCreateRequestCredentialParam{
Name: kernel.String(credential.Name),
},
},
})
if err != nil {
panic(err)
}
_ = auth
```
### Partial credentials
Credentials don't need to contain every field required by the login form. You can store what you have and collect the necessary fields from the user. `auth.connections.login()` pauses for missing values.
As an example, the below credential has email + TOTP secret stored (and automatically handled), but no password. The password is dynamically collected from the user using Kernel's Hosted UI or your Programmatic flow:
```typescript TypeScript theme={null}
const credential = await kernel.credentials.create({
name: 'my-login',
domain: 'example.com',
values: { email: 'user@example.com' }, // No password
totp_secret: 'JBSWY3DPEHPK3PXP',
});
const auth = await kernel.auth.connections.create({
domain: 'example.com',
profile_name: 'my-profile',
credential: { name: credential.name },
});
const login = await kernel.auth.connections.login(auth.id);
// Stream state changes and submit the missing password
const authEvents = await kernel.auth.connections.follow(auth.id);
for await (const event of authEvents) {
const passwordField = event.fields?.find(field => field.ref === 'password');
if (
event.event === 'managed_auth_state' &&
event.flow_step === 'AWAITING_INPUT' &&
event.interaction_id &&
passwordField
) {
// Only password is pending; email is filled from the stored credential.
await kernel.auth.connections.submit(auth.id, {
interaction_id: event.interaction_id,
field_values: { [passwordField.id]: 'user-provided-password' },
});
}
}
// TOTP auto-submitted from credential → SUCCESS
```
```python Python theme={null}
credential = await kernel.credentials.create(
name="my-login",
domain="example.com",
values={"email": "user@example.com"}, # No password
totp_secret="JBSWY3DPEHPK3PXP",
)
auth = await kernel.auth.connections.create(
domain="example.com",
profile_name="my-profile",
credential={"name": credential.name},
)
login = await kernel.auth.connections.login(auth.id)
# Stream state changes and submit the missing password
auth_events = await kernel.auth.connections.follow(auth.id)
async for event in auth_events:
password_field = next(
(field for field in (event.fields or []) if field.ref == "password"),
None,
)
if (
event.event == "managed_auth_state"
and event.flow_step == "AWAITING_INPUT"
and event.interaction_id
and password_field
):
# Only password is pending; email is filled from the stored credential.
await kernel.auth.connections.submit(
auth.id,
interaction_id=event.interaction_id,
field_values={password_field.id: "user-provided-password"},
)
# TOTP auto-submitted from credential → SUCCESS
```
```go Go theme={null}
credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{
CreateCredentialRequest: kernel.CreateCredentialRequestParam{
Name: "my-login",
Domain: "example.com",
Values: map[string]string{
"email": "user@example.com", // No password
},
TotpSecret: kernel.String("JBSWY3DPEHPK3PXP"),
},
})
if err != nil {
panic(err)
}
auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
Domain: "example.com",
ProfileName: "my-profile",
Credential: kernel.ManagedAuthCreateRequestCredentialParam{
Name: kernel.String(credential.Name),
},
},
})
if err != nil {
panic(err)
}
login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{})
if err != nil {
panic(err)
}
_ = login
// Stream state changes and submit the missing password
authEvents := client.Auth.Connections.FollowStreaming(ctx, auth.ID)
for authEvents.Next() {
event := authEvents.Current()
if event.Event != "managed_auth_state" || event.FlowStep != "AWAITING_INPUT" || event.InteractionID == "" {
continue
}
for _, field := range event.Fields {
if field.Ref != "password" {
continue
}
// Only password is pending; email is filled from the stored credential.
_, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{
SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{
InteractionID: kernel.String(event.InteractionID),
FieldValues: map[string]string{
field.ID: "user-provided-password",
},
},
})
if err != nil {
panic(err)
}
break
}
}
if err := authEvents.Err(); err != nil {
panic(err)
}
// TOTP auto-submitted from credential → SUCCESS
```
This is useful when you want to:
* Store TOTP secrets but have users enter their password each time
* Pre-fill username/email but collect password at runtime
* Merge user-provided values into an existing credential automatically on successful login
### Credential security
| Feature | Description |
| - | - |
| **Encrypted at rest** | Values encrypted using per-organization keys |
| **Write-only** | Values cannot be retrieved via API after creation |
| **Never logged** | Values are never written to logs |
| **Never shared** | Values are never passed to LLMs |
| **Isolated execution** | Authentication runs in isolated browser environments |
### Credential notes
* The `values` object is flexible and can be used to store whatever fields the login form needs (`email`, `username`, `company_id`, etc.)
* Deleting a credential unlinks it from associated connections so they can no longer auto-authenticate
* Use one credential per account. We recommend creating separate credentials for different user accounts
### Automatic reauthentication
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 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 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 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
```
## Browser region
Set `browser.region` to choose where Managed Auth runs the connection's initial login, health checks, and automatic reauthentication. Choose from `us-east`, `eu-west`, and `ap-southeast`. Region selection is available on [Start-Up and Enterprise plans](/info/pricing); omitted values default to `us-east`.
```typescript TypeScript theme={null}
const auth = await kernel.auth.connections.create({
domain: 'example.com',
profile_name: 'my-profile',
browser: { region: 'eu-west' },
});
```
```python Python theme={null}
auth = await kernel.auth.connections.create(
domain="example.com",
profile_name="my-profile",
browser={"region": "eu-west"},
)
```
```go Go theme={null}
auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
Domain: "example.com",
ProfileName: "my-profile",
Browser: kernel.ManagedAuthBrowserConfigParam{
Region: kernel.ManagedAuthBrowserConfigRegionEuWest,
},
},
})
if err != nil {
panic(err)
}
_ = auth
```
Updating `browser.region` changes the connection default for browsers created afterward. It doesn't move or restart an active login, health check, or reauthentication browser.
You can override the connection region for one login without changing its default:
```typescript TypeScript theme={null}
const login = await kernel.auth.connections.login(auth.id, {
browser: { region: 'ap-southeast' },
});
```
```python Python theme={null}
login = await kernel.auth.connections.login(
auth.id,
browser={"region": "ap-southeast"},
)
```
```go Go theme={null}
login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{
Browser: kernel.ManagedAuthBrowserConfigParam{
Region: kernel.ManagedAuthBrowserConfigRegionApSoutheast,
},
})
if err != nil {
panic(err)
}
_ = login
```
Browser placement and proxy location are independent. `browser.region` chooses where the browser runs; the connection's [proxy](/proxies/overview) controls the exit IP that websites see. Regional browsers don't provide a data residency guarantee. See [Regional Browsers](/browsers/regions) for storage and processing details.
## 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?](/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](/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)** proxies provide a static exit IP that persists across sessions, so the initial login, health checks, and reauths all exit through the same IP. The IP only changes in rare ISP-initiated replacement events or a temporary [failover to a backup endpoint](/proxies/isp#backup-endpoint-failover).
* **[Datacenter](/proxies/datacenter)** proxies assign a new exit IP per request. Sites with adaptive auth that trigger a step-up challenge (one-time code, device verification) when the client IP changes may flag these IP shifts.
* **[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 pick one if the static IP must be infrastructure you control (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](/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 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 |
| `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)
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.