FAQ

How does automatic re-authentication work?

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.

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.

How often are health checks performed?

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

• Hobbyist — minimum every 1 hour
• Start-Up — minimum every 15 minutes
• Enterprise — fully configurable

You can increase the interval above your plan’s minimum, but not below it.

What if my site’s session expires faster than the health check 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 the connection’s health_check_interval down to your plan’s minimum. Enterprise plans can go as low as 5 minutes.

How do I know if a Kernel can automatically re-authenticate a connection?

Check the can_reauth field on a connection. This boolean checks the following conditions:

1. Credential linked — A credential must be attached to the connection (stored in Kernel or via an external provider like 1Password)
2. No external action required — The learned login flow doesn’t require human intervention

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.

External actions that prevent auto-reauth

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.

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

What are sign-in options?

Sign-in options are non-MFA choices that some sites present during login, such as account pickers (“Which account do you want to use?”) or organization selectors. Unlike MFA options which are security challenges, sign-in options are informational choices that route the login flow. They appear in the session state as sign_in_options and are submitted via sign_in_option_id. See the Programmatic flow guide for details and SDK examples.

Which authentication methods are supported?

Managed Auth supports username/password authentication and most SSO providers.

Passkey-based authentication (e.g., Google accounts with passkeys enabled) is not currently supported. If a user’s SSO provider requires a passkey, the login will fail with the unsupported_auth_method error code.

What happens if login fails?

If a login attempt fails, Kernel will retry with exponential backoff. After multiple failures, the login flow 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 for the full list of error codes.

Common failure reasons include:

• Invalid credentials
• Bot detection blocking the login page
• CAPTCHAs that couldn’t be solved

Can I use Managed Auth with any website?

Managed Auth works with most websites. Sites with aggressive bot detection may require additional configuration (stealth mode, proxies). Passkeys and hardware security keys are not currently supported.

Is Managed Auth available during a trial?

Yes. Managed Auth and browser profiles are available during your trial period with the same capabilities as the plan you’re trialing.

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

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.

This is useful when your workflow needs to ensure a connection is authenticated right now, without waiting for the next scheduled health check.

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
}

What types of flows does Managed Auth support?

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 directly.

How do I debug a managed auth session?

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 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 for examples.

Can I attach multiple auth connections to one profile?

Yes. A profile can have any number of auth connections, each for a different domain. When you create a browser with that profile, it is already logged in to every connected domain.

This is useful for two common patterns:

• Multi-site workflows — Your agent visits multiple sites in a single run (e.g., reads email in Gmail, posts a summary in Slack, and updates a CRM). Attach one auth connection per site to a single profile, and the browser starts logged in to all of them.
• User-to-profile mapping — Each end user on your platform gets one profile. All of that user’s accounts (Gmail, LinkedIn, GitHub, etc.) are auth connections on their profile. When the user triggers a workflow, launch a browser with their profile.

See Profiles — Multiple auth connections per profile for code examples.

How is Managed Auth billed?

Managed Auth is included on all paid plans with no per-connection fees. It uses browser sessions to log in and keep your sessions fresh—these count toward your browser usage like any other browser session.

Auth sessions are fast (typically 5-30 seconds each). Kernel monitors session health and re-authenticates automatically when sessions expire—most stay valid for days. For example, keeping 100 auth connections logged in typically costs less than $5/month in browser usage. See Pricing & Limits for details.