> ## Documentation Index
> Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-clarify-payment-guide.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Handle website login, reuse session state, and recover eligible connections automatically

managed auth handles website login and saves authenticated state to a reusable browser profile for your agents. KERNEL monitors the connection and can attempt automatic reauthentication for eligible flows that can complete without human input.

managed auth stores authentication state in [browser profiles](/browsers/profiles). profiles can also persist and reuse browser state without managed auth.

use managed auth when you want KERNEL to orchestrate login and session recovery, and your application can bring the user back when authentication requires their input. use [Fill from Vault](/auth/fill-from-vault) when your application or agent needs to control navigation, credential filling, submission, and recovery in its current browser session.

<Note>
  with automatic recovery enabled, KERNEL can attempt to sign in again when a health check confirms that a session has expired. recovery isn't guaranteed. if the site requires an email or sms code, approval, or another user action, your application must bring the user back to complete a new login. see [connection lifecycle](/auth/connection-lifecycle) for eligibility and recovery details.
</Note>

## How it works

<Steps>
  <Step title="Create a Connection">
    A **Managed Auth Connection** attaches a domain's authentication state to a browser [profile](/browsers/profiles) so future browsers can reuse it. A single profile can have multiple auth connections, one per domain.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const auth = await kernel.auth.connections.create({
        domain: 'netflix.com',
        profile_name: 'netflix-user-123',
      });
      ```

      ```python Python theme={null}
      auth = await kernel.auth.connections.create(
          domain="netflix.com",
          profile_name="netflix-user-123",
      )
      ```

      ```go Go theme={null}
      auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
      	ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
      		Domain:      "netflix.com",
      		ProfileName: "netflix-user-123",
      	},
      })
      if err != nil {
      	panic(err)
      }
      _ = auth
      ```
    </CodeGroup>
  </Step>

  <Step title="Start a Login Session">
    A **Managed Auth Session** is the corresponding login flow for the specified connection. Users provide credentials via a KERNEL-hosted page or your own UI.

    link a [credential](/auth/credentials) so KERNEL can attempt reauthentication when the connection is eligible. stored credentials alone don't make every flow eligible.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const login = await kernel.auth.connections.login(auth.id);

      // Send user to login page
      console.log('Login URL:', login.hosted_url);

      // Stream state changes until the flow completes
      const events = await kernel.auth.connections.follow(auth.id);
      let finalState;

      for await (const event of events) {
        if (event.event === 'managed_auth_state') {
          finalState = event;
        }
      }

      if (finalState?.flow_status === 'SUCCESS') {
        console.log('Authenticated!');
      }
      ```

      ```python Python theme={null}
      login = await kernel.auth.connections.login(auth.id)

      # Send user to login page
      print(f"Login URL: {login.hosted_url}")

      # Stream state changes until the flow completes
      events = await kernel.auth.connections.follow(auth.id)
      final_state = None

      async for event in events:
          if event.event == "managed_auth_state":
              final_state = event

      if final_state and final_state.flow_status == "SUCCESS":
          print("Authenticated!")
      ```

      ```go Go theme={null}
      login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{})
      if err != nil {
      	panic(err)
      }

      // Send user to login page
      fmt.Println("Login URL:", login.HostedURL)

      // Stream state changes until the flow completes
      events := client.Auth.Connections.FollowStreaming(ctx, auth.ID)
      authenticated := false

      for events.Next() {
      	event := events.Current()
      	if event.Event == "managed_auth_state" && event.FlowStatus == "SUCCESS" {
      		authenticated = true
      	}
      }
      if err := events.Err(); err != nil {
      	panic(err)
      }

      if authenticated {
      	fmt.Println("Authenticated!")
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Use the Profile">
    Once the auth connection completes, the authenticated session is saved to the browser [profile](/browsers/profiles) specified in step 1. You can attach additional auth connections to the same profile for other domains. When you create a browser with the profile, it loads the saved authentication state for every connected domain.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const browser = await kernel.browsers.create({
        profile: { name: 'netflix-user-123' },
        stealth: true,
      });

      // Navigate with the saved authentication state
      await page.goto('https://netflix.com');
      ```

      ```python Python theme={null}
      browser = await kernel.browsers.create(
          profile={"name": "netflix-user-123"},
          stealth=True,
      )

      # Navigate with the saved authentication state
      await page.goto("https://netflix.com")
      ```

      ```go Go theme={null}
      browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
      	Profile: shared.BrowserProfileParam{
      		Name: kernel.String("netflix-user-123"),
      	},
      	Stealth: kernel.Bool(true),
      })
      if err != nil {
      	panic(err)
      }
      _ = browser

      // Navigate with the saved authentication state
      _, err = client.Browsers.Playwright.Execute(ctx, browser.SessionID, kernel.BrowserPlaywrightExecuteParams{
      	Code: `await page.goto("https://netflix.com");`,
      })
      if err != nil {
      	panic(err)
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

these steps establish the initial connection. your integration must also handle `NEEDS_AUTH`: start a new interactive login and bring the user back when a code, choice, or approval is required. wait for successful authentication before resuming work that requires the account. periodic health checks and eligible automatic reauthentication attempts don't replace this recovery path. see [connection lifecycle](/auth/connection-lifecycle) for runtime behavior and configuration options.

## Choose your integration

<CardGroup cols={3}>
  <Card title="Hosted UI" icon="browser" href="/auth/hosted-ui">
    **Start here** - Simplest integration

    Redirect users to KERNEL's hosted page. Add features incrementally: save credentials for eligible automatic reauthentication, set custom login URLs, and configure SSO.
  </Card>

  <Card title="React Component" icon="react" href="/auth/react">
    **Embed in your app** - Drop-in component

    Mount `<KernelManagedAuth />` on a route in your own app. Same flow as Hosted UI, rendered on your origin and trivial to restyle to match your brand.
  </Card>

  <Card title="Programmatic" icon="code" href="/auth/programmatic">
    **Custom Managed Auth UI** - Custom UI or headless

    Build your own credential collection. Handle login fields, SSO buttons, MFA selection, and external actions (push notifications, security keys).
  </Card>
</CardGroup>

## Why Managed Auth?

Managed Auth runs **login flows** by navigating login pages, filling credentials, following SSO redirects, and guiding users through additional authentication steps. It saves the resulting session state to a reusable profile.

The most valuable workflows live behind logins. Managed Auth provides:

* **Broad site coverage** - Login pages are discovered and handled across common website login flows
* **SSO/OAuth support** - KERNEL follows common SSO redirects. Common provider domains are allowed by default; add custom provider domains to `allowed_domains`
* **2FA/OTP handling** - KERNEL can generate totp codes when the credential includes a totp secret. email and sms codes, approvals, and other user-required steps need an interactive login
* **Post-login URL** - Get the URL where login landed (`post_login_url`) so you can start automations from the right page
* **Session monitoring** - [Periodic health checks](/auth/connection-lifecycle) and eligible automatic reauthentication attempts
* **Secure by default** - Credentials are encrypted at rest and never exposed in API responses or passed to LLMs

## Security

| Feature                    | Description                                        |
| -------------------------- | -------------------------------------------------- |
| **Encrypted credentials**  | Values encrypted with per-organization keys        |
| **No credential exposure** | Never returned in API responses or passed to LLMs  |
| **Encrypted profiles**     | Browser session state encrypted end-to-end         |
| **Isolated execution**     | Each login runs in an isolated browser environment |

## When to use Fill from Vault

Use [Fill from Vault](/auth/fill-from-vault) when an end user owns the credentials, remains present during the task, and might need to respond to an authentication prompt mid-workflow. Your application or agent controls navigation, chooses the fields to fill, submits the form, and handles the site's response. KERNEL collects and stores sensitive values, then fills them without returning them through the api.