Skip to content

Commit 867358b

Browse files
dprevoznikdprevoznik
authored
auth: dedicated page for health checks and re-auth (#365)
* auth: dedicated page for health checks and re-auth Consolidates scattered FAQ entries on health check cadence, can_reauth eligibility, manual re-auth, login failure codes, and debugging into a single Health Checks & Re-Auth page. FAQ entries now defer to the new page with a short summary and link. Overview links to it from the Session monitoring bullet. * auth: rename health checks page title to Health Checks * auth: address review feedback on lifecycle page - Rename page to Connection Lifecycle (auth/connection-lifecycle.mdx) to match the page's scope beyond just health checks - Fix Start-Up minimum interval (15 min -> 20 min) to match StartupMinHealthCheckIntervalSeconds in the API - Move nav position to right after Configuration, before Credentials - Slim Debugging section to the per-login override; link out to Connection Configuration for the connection-wide record_session flag - Add a pointer from overview's How It Works to the lifecycle page so the integration loop and runtime loop don't compete - Update cross-links in faq + overview to the new path
1 parent f3d8c0e commit 867358b

4 files changed

Lines changed: 158 additions & 71 deletions

File tree

‎auth/connection-lifecycle.mdx‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: "Connection Lifecycle"
3+
description: "How connections stay authenticated, and what to do when one breaks"
4+
---
5+
6+
Once a Managed Auth connection is `AUTHENTICATED`, Kernel runs periodic health checks and automatic re-authentication to keep the session valid. This page covers the runtime lifecycle of a connection: how the check-and-reauth loop works, how to tune it, what blocks auto-reauth, and how to debug a connection that won't stay logged in.
7+
8+
## The lifecycle
9+
10+
After the initial login, every connection moves through this loop:
11+
12+
<Steps>
13+
<Step title="Health check">
14+
On a configurable cadence, Kernel spins up a browser with the profile and verifies the session is still logged in. If it is, nothing else happens until the next check.
15+
</Step>
16+
<Step title="Auto-reauth (if eligible)">
17+
If the check finds the session expired and the connection's `can_reauth` is `true`, Kernel runs the saved login flow with the stored credentials in the background. A successful login resets the loop.
18+
</Step>
19+
<Step title="NEEDS_AUTH (if not eligible, or auto-reauth fails)">
20+
If auto-reauth isn't possible — credentials aren't linked, the saved flow requires human input, or the login keeps failing — the connection's `status` flips to `NEEDS_AUTH` and a new login session is required.
21+
</Step>
22+
</Steps>
23+
24+
## Cadence
25+
26+
Health checks run on a configurable interval. Your plan sets the minimum:
27+
28+
| Plan | Minimum interval |
29+
|------|------------------|
30+
| Hobbyist | 1 hour |
31+
| Start-Up | 20 minutes |
32+
| Enterprise | Fully configurable (as low as 5 minutes) |
33+
34+
You can raise the interval above your plan's minimum, but not below it. Update it with `health_check_interval` (in seconds) — changes take effect immediately, so the next check uses the new value:
35+
36+
<CodeGroup>
37+
```typescript TypeScript
38+
await kernel.auth.connections.update(auth.id, {
39+
health_check_interval: 1800, // 30 minutes
40+
});
41+
```
42+
43+
```python Python
44+
await kernel.auth.connections.update(
45+
auth.id,
46+
health_check_interval=1800, # 30 minutes
47+
)
48+
```
49+
</CodeGroup>
50+
51+
### Sessions that expire faster than the interval
52+
53+
Kernel keeps re-authenticating even when every health check finds the session expired. A successful login resets the auto-reauth state, so a site whose session TTL is shorter than your health check interval is re-authenticated on every cycle rather than being given up on.
54+
55+
If you're seeing the connection flip to `NEEDS_AUTH` frequently and want shorter detection windows, lower `health_check_interval` toward your plan's minimum.
56+
57+
## Can this connection auto-reauth?
58+
59+
Check the `can_reauth` boolean on a connection. It's `true` only when **both** of these hold:
60+
61+
1. **A credential is linked** — stored in Kernel or sourced via [1Password](/integrations/1password).
62+
2. **No external action is required** — the saved login flow doesn't need a human (no SMS/email OTP, no push notification, no manual MFA selection).
63+
64+
If either fails, the connection will move to `NEEDS_AUTH` on the next expired session and wait for a fresh login.
65+
66+
### External actions that block auto-reauth
67+
68+
After a successful login, Kernel saves the login flow. If that flow includes steps that require human action, the connection can't auto-reauth because those steps can't be replayed without user input.
69+
70+
If your flow requires one of these, you can still automate around it:
71+
72+
- **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.
73+
- **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.
74+
75+
## Triggering re-auth manually
76+
77+
Call `.login()` on any connection to trigger authentication immediately, without waiting for the next scheduled health check. If the profile is already logged in, it returns quickly without starting a new flow. If the connection needs auth, it starts a new login session.
78+
79+
This is useful when your workflow needs to ensure a connection is authenticated *right now*:
80+
81+
<CodeGroup>
82+
```typescript TypeScript
83+
const state = await kernel.auth.connections.retrieve(auth.id);
84+
85+
if (state.status === 'NEEDS_AUTH') {
86+
const login = await kernel.auth.connections.login(auth.id);
87+
// Handle login flow as usual
88+
}
89+
```
90+
91+
```python Python
92+
state = await kernel.auth.connections.retrieve(auth.id)
93+
94+
if state.status == "NEEDS_AUTH":
95+
login = await kernel.auth.connections.login(auth.id)
96+
# Handle login flow as usual
97+
```
98+
</CodeGroup>
99+
100+
## When a login fails
101+
102+
If a login attempt fails — whether triggered by a health check, an auto-reauth, or a manual `.login()` — Kernel retries with exponential backoff. After repeated failures the flow is marked failed and the connection surfaces an error code on `flow_status`.
103+
104+
Common codes:
105+
106+
| Code | Meaning |
107+
|------|---------|
108+
| `credentials_invalid` | The stored or submitted credentials were rejected by the site. |
109+
| `bot_detected` | The login page blocked the session as automated. |
110+
| `captcha_blocked` | A CAPTCHA was presented and couldn't be solved. |
111+
| `unsupported_auth_method` | The site required a method Kernel doesn't currently support (e.g. passkeys). |
112+
113+
See the [API reference](https://kernel.sh/docs/api-reference/managed-auth/start-login-flow) for the full list.
114+
115+
### Recovering
116+
117+
- **`credentials_invalid`** — Update the linked [credential](/auth/credentials) and call `.login()` to re-run the flow.
118+
- **`bot_detected` / `captcha_blocked`** — Pin the connection to a cleaner [proxy](/auth/configuration#custom-proxy) (ISP or custom). For aggressive sites, also enable stealth and review the [bot detection guide](/browsers/bot-detection/overview).
119+
- **`unsupported_auth_method`** — Switch the account to a supported sign-in method (e.g. password + TOTP instead of a passkey) and re-link the credential.
120+
121+
## Debugging a flaky connection
122+
123+
Two tools handle most investigations:
124+
125+
1. **Dashboard live view** — The **Browser Sessions** tab in the Kernel dashboard shows every auth browser session (logins, health checks, reauths) with a live view. Watch a session in real time to see exactly where it's getting stuck.
126+
127+
2. **Session recordings** — To record only the next single login attempt without recording subsequent health checks and reauths, pass `record_session: true` on `.login()`:
128+
129+
<CodeGroup>
130+
```typescript TypeScript
131+
const login = await kernel.auth.connections.login(auth.id, {
132+
record_session: true,
133+
});
134+
```
135+
136+
```python Python
137+
login = await kernel.auth.connections.login(
138+
auth.id,
139+
record_session=True,
140+
)
141+
```
142+
</CodeGroup>
143+
144+
To record every auth session on the connection (logins, health checks, and reauths), set `record_session: true` connection-wide — see [Record Sessions for Debugging](/auth/configuration#record-sessions-for-debugging).
145+
146+
## See also
147+
148+
- [Connection Configuration](/auth/configuration) — `health_check_interval`, `proxy`, `record_session`, and other shared options
149+
- [Credentials](/auth/credentials) — what gets stored and how it powers auto-reauth
150+
- [FAQ](/auth/faq) — quick answers to common questions

‎auth/faq.mdx‎

Lines changed: 4 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -4,44 +4,7 @@ title: FAQ
44

55
## How does automatic re-authentication work?
66

7-
When you link credentials to a connection, Kernel monitors the login session and re-authenticates automatically when it expires. Periodic health checks detect logged-out sessions and trigger re-auth in the background, so the profile stays logged in without additional action on your part.
8-
9-
<Warning>
10-
Automatic re-authentication only works when the stored credentials are complete and don't require human input. If login needs SMS/email OTP, push notifications, or manual MFA selection, you'll need to trigger a new login session manually.
11-
</Warning>
12-
13-
14-
## How often are health checks performed?
15-
16-
Health checks run on configurable cadences. Your plan sets the minimum interval:
17-
- **Hobbyist** — minimum every 1 hour
18-
- **Start-Up** — minimum every 15 minutes
19-
- **Enterprise** — fully configurable
20-
21-
You can increase the interval above your plan's minimum, but not below it.
22-
23-
## What if my site's session expires faster than the health check interval?
24-
25-
Kernel keeps re-authenticating even when every health check finds the session expired. A successful login resets the auto-reauth state, so a site whose session TTL is shorter than your health check interval is re-authenticated on every cycle rather than being given up on.
26-
27-
If you're seeing the connection flip to `NEEDS_AUTH` frequently and want shorter detection windows, lower the connection's `health_check_interval` down to your plan's minimum. Enterprise plans can go as low as 5 minutes.
28-
29-
## How do I know if a Kernel can automatically re-authenticate a connection?
30-
31-
Check the `can_reauth` field on a connection. This boolean checks the following conditions:
32-
33-
1. **Credential linked** — A credential must be attached to the connection (stored in Kernel or via an external provider like [1Password](/integrations/1password))
34-
2. **No external action required** — The learned login flow doesn't require human intervention
35-
36-
Only if all of the above conditions are met will `can_reauth` be `true`. When true, Kernel will attempt to automatically re-authenticate the connection.
37-
38-
### External actions that prevent auto-reauth
39-
40-
After a successful login, Kernel saves the login flow. If the flow includes steps that require human action—like SMS/email OTP, push notifications, or manual MFA selection—Kernel marks the connection as unable to auto-reauth because those steps can't be automated without user input.
41-
42-
If your login flow requires one of these, you can still automate around it:
43-
- **Switch to TOTP** — If the site supports authenticator apps, add a `totp_secret` to your credential. TOTP codes are generated automatically, so the login flow won't require external action. If a TOTP code expires or times out before the site accepts it, Kernel automatically retries with a fresh code.
44-
- **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.
7+
When you link credentials to a connection, Kernel runs periodic health checks, detects logged-out sessions, and re-authenticates in the background so the profile stays logged in. See [Connection Lifecycle](/auth/connection-lifecycle) for the full lifecycle, cadence options, and `can_reauth` rules.
458

469
## What are sign-in options?
4710

@@ -57,13 +20,7 @@ Passkey-based authentication (e.g., Google accounts with passkeys enabled) is no
5720

5821
## What happens if login fails?
5922

60-
If a login attempt fails, Kernel will retry with exponential backoff. After multiple failures, the [login flow](/auth/hosted-ui) will be marked as failed and you'll receive an error with a specific error code. Common codes include `credentials_invalid`, `bot_detected`, and `captcha_blocked`. See the [API reference](https://kernel.sh/docs/api-reference/managed-auth/start-login-flow) for the full list of error codes.
61-
62-
Common failure reasons include:
63-
64-
- Invalid credentials
65-
- Bot detection blocking the login page
66-
- CAPTCHAs that couldn't be solved
23+
Kernel retries with exponential backoff, then surfaces an error code (`credentials_invalid`, `bot_detected`, `captcha_blocked`, etc.). See [Connection Lifecycle](/auth/connection-lifecycle#when-a-login-fails) for the full list and recovery steps.
6724

6825
## Can I use Managed Auth with any website?
6926

@@ -75,38 +32,15 @@ Yes. Managed Auth and browser profiles are available during your trial period wi
7532

7633
## How do I re-authenticate a connection before the next health check?
7734

78-
Call `.login()` on any connection at any time to trigger authentication immediately. If the profile is already logged in, it returns quickly without starting a new flow. If the connection needs auth, it starts a new login session.
79-
80-
This is useful when your workflow needs to ensure a connection is authenticated right now, without waiting for the next scheduled health check.
81-
82-
<CodeGroup>
83-
```typescript TypeScript
84-
const state = await kernel.auth.connections.retrieve(auth.id);
85-
86-
if (state.status === 'NEEDS_AUTH') {
87-
const login = await kernel.auth.connections.login(auth.id);
88-
// Handle login flow as usual
89-
}
90-
```
91-
92-
```python Python
93-
state = await kernel.auth.connections.retrieve(auth.id)
94-
95-
if state.status == "NEEDS_AUTH":
96-
login = await kernel.auth.connections.login(auth.id)
97-
# Handle login flow as usual
98-
```
99-
</CodeGroup>
35+
Call `.login()` on the connection to trigger auth immediately. See [Triggering re-auth manually](/auth/connection-lifecycle#triggering-re-auth-manually) for the pattern.
10036

10137
## What types of flows does Managed Auth support?
10238

10339
Managed Auth handles login and authentication flows end-to-end: entering credentials, multi-step login forms (e.g. email on one page, password on the next), SSO redirects, MFA challenges, and keeping sessions alive. For post-login browser work like form filling, sign-ups, or other workflows, use [Kernel's browser automation](/browsers/create-a-browser) directly.
10440

10541
## How do I debug a managed auth session?
10642

107-
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.
108-
109-
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.
43+
Use the **Browser Sessions** tab in the dashboard for live view, or set `record_session: true` to capture replays of every auth browser session. See [Debugging a flaky connection](/auth/connection-lifecycle#debugging-a-flaky-connection) for details.
11044

11145
## Can I attach multiple auth connections to one profile?
11246

‎auth/overview.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,8 @@ await page.goto("https://netflix.com")
9797
</Step>
9898
</Steps>
9999

100+
The steps above are the integration loop — what you wire up once per connection. After the initial login, the connection enters its runtime loop of periodic health checks and automatic re-authentication; see [Connection Lifecycle](/auth/connection-lifecycle) for how that works and how to tune it.
101+
100102
## Choose Your Integration
101103

102104
<CardGroup cols={3}>
@@ -128,7 +130,7 @@ The most valuable workflows live behind logins. Managed Auth provides:
128130
- **SSO/OAuth support** - "Sign in with Google/GitHub/Microsoft" buttons work out-of-the-box, with common SSO provider domains automatically allowed
129131
- **2FA/OTP handling** - TOTP codes automated with automatic retry on expiry, SMS/email/push OTP are supported
130132
- **Post-login URL** - Get the URL where login landed (`post_login_url`) so you can start automations from the right page
131-
- **Session monitoring** - Automatic re-authentication when sessions expire with stored credentials
133+
- **Session monitoring** - [Periodic health checks](/auth/connection-lifecycle) and automatic re-authentication when sessions expire with stored credentials
132134
- **Secure by default** - Credentials encrypted at rest, never exposed in API responses, or passed to LLMs
133135

134136
## Security

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@
104104
]
105105
},
106106
"auth/configuration",
107+
"auth/connection-lifecycle",
107108
"auth/credentials",
108109
"auth/profiles",
109110
"auth/faq"

0 commit comments

Comments
 (0)