Connection Lifecycle

How connections stay authenticated, and what to do when one breaks

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.

The lifecycle

After the initial login, every connection moves through this loop:

1. Health check

   On a configurable cadence, Kernel spins up a browser with the profile and verifies the session. A check reaches one of three conclusions: still logged in, definitely logged out, or inconclusive — the page didn’t prove either way.

   A check needs concrete evidence to conclude. If the site returns a challenge page, times out, partially loads, or shows something ambiguous, the result is inconclusive and the connection is left exactly as it was. Nothing happens until the next check.

2. Auto-reauth (if eligible)

   If the check finds the session definitely 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.

   An inconclusive check never triggers reauth. Kernel would rather check again on the next cycle than log in again unnecessarily — a spurious login can trip risk checks on the site, prompt a device-verification email, or invalidate a working session.

3. NEEDS_AUTH (if not eligible, or auto-reauth fails)

   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.

Cadence

Health checks run on a configurable interval. Your plan sets the minimum:

Plan	Minimum interval
Hobbyist	1 hour
Start-Up	20 minutes
Enterprise	Fully configurable (as low as 5 minutes)

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:

TypeScript

await kernel.auth.connections.update(auth.id, {
  health_check_interval: 1800, // 30 minutes
});

Sessions that expire faster than the interval

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.

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.

Can this connection auto-reauth?

Check the can_reauth boolean on a connection. It’s true only when both of these hold:

1. A credential is linked — stored in Kernel or sourced via 1Password.
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).

If either fails, the connection will move to NEEDS_AUTH on the next expired session and wait for a fresh login.

External actions that block auto-reauth

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.

If your flow requires one of these, you can still automate around it:

• 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.
• Trigger manual re-auth — Start a new login session and route the user through the Hosted UI or Programmatic flow.

Triggering re-auth manually

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.

This is useful when your workflow needs to ensure a connection is authenticated right now:

TypeScript

const state = await kernel.auth.connections.retrieve(auth.id);

if (state.status === 'NEEDS_AUTH') {
  const login = await kernel.auth.connections.login(auth.id);
  // Handle login flow as usual
}

When a login fails

If a login attempt fails — whether triggered by a health check, an auto-reauth, or a manual .login() — the flow is marked failed and the connection surfaces an error code on flow_status.

How much Kernel retries depends on the failure. A transient site problem (a 5xx page, a maintenance screen) is retried once against the login page before giving up. A conclusive rejection by the site — wrong credentials, a locked account, an unsupported method — is not retried, because retrying would burn attempts against a lockout or fail identically.

Common codes:

Code	Meaning	Retried
credentials_invalid	The stored or submitted credentials were rejected by the site.	No
account_locked	The site locked or suspended the account.	No
unsupported_auth_method	The site required a method Kernel doesn’t currently support (e.g. passkeys).	No
rate_limited	The site rate-limited the login attempt.	Yes, after a delay
website_error	The site returned an error, maintenance, or unavailable page.	Once
bot_detected	The login page blocked the session as automated.	No
captcha_blocked	A CAPTCHA was presented and couldn’t be solved.	No

See the API reference for the full list.

Recovering

• credentials_invalid — Update the linked credential and call .login() to re-run the flow. During an interactive login, Kernel asks for a corrected value in place rather than failing the whole flow — see replacing a rejected credential.
• account_locked — Unlock the account with the site directly. Calling .login() again before that will not help and may extend the lockout.
• bot_detected / captcha_blocked — Pin the connection to a cleaner proxy (ISP or custom). For aggressive sites, also enable stealth and review the bot detection guide.
• 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.
• website_error — Usually the site, not the connection. Retry later; if it persists, confirm the connection’s login_url still points at a working login page.

Debugging a flaky connection

Two tools handle most investigations:

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.

2. Session recordings — To record only the next single login attempt without recording subsequent health checks and reauths, pass record_session: true on .login():

TypeScript

const login = await kernel.auth.connections.login(auth.id, {
  record_session: true,
});

To record every auth session on the connection (logins, health checks, and reauths), set record_session: true connection-wide — see Record Sessions for Debugging.

See also

• Connection Configuration — health_check_interval, proxy, record_session, and other shared options
• Credentials — what gets stored and how it powers auto-reauth
• FAQ — quick answers to common questions