Programmatic Flow

Build your own credential collection UI instead of using the hosted page. Stream login events, then submit credentials via the API. Use the Programmatic flow when:

You need a custom credential collection UI that matches your app’s design
You’re building headless/automated authentication
You have credentials stored and want to authenticate without user interaction

How It Works

Create Connection and Start Session

Same as Hosted UI

Stream and Submit

Follow the connection’s SSE stream and submit credentials when flow_step becomes AWAITING_INPUT

Handle 2FA

If more fields appear (2FA code), submit again—same loop handles it

Getting started

1. Create a Connection

A Managed Auth Connection attaches an authenticated domain to a profile so you can use the auth connection in future browsers. A single profile can hold multiple auth connections — create one connection for each domain you want to keep authenticated on that profile.

const auth = await kernel.auth.connections.create({
  domain: 'github.com',
  profile_name: 'github-profile', // Name of the profile to associate with the connection
});

auth = await kernel.auth.connections.create(
    domain="github.com",
    profile_name="github-profile", # Name of the profile to associate with the connection
)

auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
	ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
		Domain:      "github.com",
		ProfileName: "github-profile", // Name of the profile to associate with the connection
	},
})
if err != nil {
	panic(err)
}
_ = auth

const login = await kernel.auth.connections.login(auth.id);

login = await kernel.auth.connections.login(auth.id)

login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{})
if err != nil {
	panic(err)
}
_ = login

Credentials are saved automatically on successful login, enabling automatic re-authentication when the session expires.

3. Stream and submit credentials

A single SSE stream handles everything—initial login, 2FA, and completion:

const events = await kernel.auth.connections.follow(auth.id);
let finalState;

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

  // Submit when fields are ready (login or 2FA)
  if (event.flow_step === 'AWAITING_INPUT' && event.discovered_fields?.length) {
    const fieldValues = getCredentialsForFields(event.discovered_fields);
    await kernel.auth.connections.submit(auth.id, { fields: fieldValues });
  }
}

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

events = await kernel.auth.connections.follow(auth.id)
final_state = None

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

    # Submit when fields are ready (login or 2FA)
    if event.flow_step == "AWAITING_INPUT" and event.discovered_fields:
        field_values = get_credentials_for_fields(event.discovered_fields)
        await kernel.auth.connections.submit(auth.id, fields=field_values)

if final_state and final_state.flow_status == "SUCCESS":
    print("Authentication successful!")

events := client.Auth.Connections.FollowStreaming(ctx, auth.ID)
authenticated := false

for events.Next() {
	event := events.Current()
	if event.Event != "managed_auth_state" {
		continue
	}
	if event.FlowStatus == "SUCCESS" {
		authenticated = true
	}

	// Submit when fields are ready (login or 2FA)
	if event.FlowStep == "AWAITING_INPUT" && len(event.DiscoveredFields) > 0 {
		fieldValues := map[string]string{}
		missingFields := []string{}

		for _, field := range event.DiscoveredFields {
			switch field.Name {
			case "username":
				fieldValues[field.Name] = "dev-user"
			case "email":
				fieldValues[field.Name] = "dev@example.com"
			case "password":
				fieldValues[field.Name] = "correct-horse-battery-staple"
			case "otp", "code", "totp":
				fieldValues[field.Name] = "123456"
			default:
				switch field.Type {
				case "email":
					fieldValues[field.Name] = "dev@example.com"
				case "password":
					fieldValues[field.Name] = "correct-horse-battery-staple"
				case "code", "totp":
					fieldValues[field.Name] = "123456"
				default:
					missingFields = append(missingFields, field.Name)
				}
			}
		}

		if len(missingFields) > 0 {
			fmt.Println("Collect values for fields:", missingFields)
			break
		}

		_, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{
			SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{
				Fields: fieldValues,
			},
		})
		if err != nil {
			panic(err)
		}
	}
}
if err := events.Err(); err != nil {
	panic(err)
}

if authenticated {
	fmt.Println("Authentication successful!")
}

The discovered_fields array tells you what the login form needs:

// Example discovered_fields for login
[{ name: 'username', type: 'text' }, { name: 'password', type: 'password' }]

// Example discovered_fields for 2FA
[{ name: 'otp', type: 'code' }]

Complete Example

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

// Create connection
const auth = await kernel.auth.connections.create({
  domain: 'github.com',
  profile_name: 'github-profile',
});

const login = await kernel.auth.connections.login(auth.id);

// One SSE stream handles login + 2FA
const events = await kernel.auth.connections.follow(auth.id);
let finalState;

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

  if (event.flow_step === 'AWAITING_INPUT' && event.discovered_fields?.length) {
    // Check what fields are needed
    const fieldNames = event.discovered_fields.map(f => f.name);

    if (fieldNames.includes('username')) {
      // Initial login
      await kernel.auth.connections.submit(auth.id, {
        fields: { username: 'my-username', password: 'my-password' }
      });
    } else {
      // 2FA or additional fields
      const code = await promptUserForCode();
      await kernel.auth.connections.submit(auth.id, {
        fields: { [event.discovered_fields[0].name]: code }
      });
    }
  }
}

if (finalState?.flow_status === 'SUCCESS') {
  console.log('Authentication successful!');
  
  const browser = await kernel.browsers.create({
    profile: { name: 'github-profile' },
    stealth: true,
  });
  
  // Navigate to the site—you're already logged in
  await page.goto('https://github.com');
}

from kernel import AsyncKernel

kernel = AsyncKernel()

# Create connection
auth = await kernel.auth.connections.create(
    domain="github.com",
    profile_name="github-profile",
)

login = await kernel.auth.connections.login(auth.id)

# One SSE stream handles login + 2FA
events = await kernel.auth.connections.follow(auth.id)
final_state = None

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

    if event.flow_step == "AWAITING_INPUT" and event.discovered_fields:
        # Check what fields are needed
        field_names = [field.name for field in event.discovered_fields]

        if "username" in field_names:
            # Initial login
            await kernel.auth.connections.submit(
                auth.id,
                fields={"username": "my-username", "password": "my-password"},
            )
        else:
            # 2FA or additional fields
            code = input("Enter code: ")
            await kernel.auth.connections.submit(
                auth.id,
                fields={event.discovered_fields[0].name: code},
            )

if final_state and final_state.flow_status == "SUCCESS":
    print("Authentication successful!")
    
    browser = await kernel.browsers.create(
        profile={"name": "github-profile"},
        stealth=True,
    )
    
    # Navigate to the site—you're already logged in
    await page.goto("https://github.com")

package main

import (
	"context"
	"fmt"

	"github.com/kernel/kernel-go-sdk"
	"github.com/kernel/kernel-go-sdk/shared"
)

func promptUserForCode() string {
	return "123456"
}

func main() {
	ctx := context.Background()
	client := kernel.NewClient()

	// Create connection
	auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{
		ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{
			Domain:      "github.com",
			ProfileName: "github-profile",
		},
	})
	if err != nil {
		panic(err)
	}

	login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{})
	if err != nil {
		panic(err)
	}
	_ = login

	// One SSE stream handles login + 2FA
	events := client.Auth.Connections.FollowStreaming(ctx, auth.ID)
	authenticated := false

	for events.Next() {
		event := events.Current()
		if event.Event != "managed_auth_state" {
			continue
		}
		if event.FlowStatus == "SUCCESS" {
			authenticated = true
		}

		if event.FlowStep == "AWAITING_INPUT" && len(event.DiscoveredFields) > 0 {
			// Check what fields are needed
			fieldNames := map[string]bool{}
			for _, field := range event.DiscoveredFields {
				fieldNames[field.Name] = true
			}

			if fieldNames["username"] {
				// Initial login
				_, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{
					SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{
						Fields: map[string]string{
							"username": "my-username",
							"password": "my-password",
						},
					},
				})
				if err != nil {
					panic(err)
				}
			} else {
				// 2FA or additional fields
				code := promptUserForCode()
				_, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{
					SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{
						Fields: map[string]string{
							event.DiscoveredFields[0].Name: code,
						},
					},
				})
				if err != nil {
					panic(err)
				}
			}
		}
	}
	if err := events.Err(); err != nil {
		panic(err)
	}

	if authenticated {
		fmt.Println("Authentication successful!")

		browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
			Profile: shared.BrowserProfileParam{
				Name: kernel.String("github-profile"),
			},
			Stealth: kernel.Bool(true),
		})
		if err != nil {
			panic(err)
		}

		// Navigate to the site—you're already logged in
		_, err = client.Browsers.Playwright.Execute(ctx, browser.SessionID, kernel.BrowserPlaywrightExecuteParams{
			Code: `await page.goto("https://github.com");`,
		})
		if err != nil {
			panic(err)
		}
	}
}

This example covers username/password login with 2FA — the most common flow. If the site uses SSO, MFA selection, account pickers, or external actions (push notifications), see Handling Different Input Types below for how to handle each case.

Every programmatic login session also has a hosted_url. If your flow encounters an unexpected state, you can redirect the user to this URL to complete login via the Hosted UI instead.

Handling Different Input Types

The SSE event loop handles discovered_fields, but login pages can require other input types too. In the examples below, state is the current managed_auth_state event from the stream.

SSO Buttons

When the login page has “Sign in with Google/GitHub/Microsoft” buttons, they appear in pending_sso_buttons:

if (state.pending_sso_buttons?.length) {
  // Show the user available SSO options
  for (const btn of state.pending_sso_buttons) {
    console.log(`${btn.provider}: ${btn.label}`);
  }
  
  // Submit the selected SSO button
  await kernel.auth.connections.submit(auth.id, {
    sso_button_selector: state.pending_sso_buttons[0].selector
  });
}

if state.pending_sso_buttons:
    # Show the user available SSO options
    for btn in state.pending_sso_buttons:
        print(f"{btn['provider']}: {btn['label']}")
    
    # Submit the selected SSO button
    await kernel.auth.connections.submit(
        auth.id,
        sso_button_selector=state.pending_sso_buttons[0]["selector"],
    )

if len(state.PendingSSOButtons) > 0 {
	// Show the user available SSO options
	for _, btn := range state.PendingSSOButtons {
		fmt.Printf("%s: %s\n", btn.Provider, btn.Label)
	}

	// Submit the selected SSO button
	_, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{
		SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{
			SSOButtonSelector: kernel.String(state.PendingSSOButtons[0].Selector),
		},
	})
	if err != nil {
		panic(err)
	}
}

Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are automatically allowed. For custom OAuth providers, add their domains to allowed_domains on the connection.

SSO Provider Selection

As an alternative to clicking an SSO button by selector, you can submit the SSO provider name directly. When SSO buttons are detected, the session state includes a sso_provider field (a string) identifying the provider that Kernel recommends. You can also specify a provider explicitly using the sso_provider submit parameter:

if (state.pending_sso_buttons?.length) {
  // Submit by provider name instead of selector
  await kernel.auth.connections.submit(auth.id, {
    sso_provider: state.pending_sso_buttons[0].provider  // e.g., "google"
  });
}

if state.pending_sso_buttons:
    # Submit by provider name instead of selector
    await kernel.auth.connections.submit(
        auth.id,
        sso_provider=state.pending_sso_buttons[0]["provider"],  # e.g., "google"
    )

if len(state.PendingSSOButtons) > 0 {
	// Submit by provider name instead of selector
	_, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{
		SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{
			SSOProvider: kernel.String(state.PendingSSOButtons[0].Provider), // e.g., "google"
		},
	})
	if err != nil {
		panic(err)
	}
}

sso_provider is a singular string value, not an array. Use sso_button_selector when you need to click a specific button by its CSS selector, and sso_provider when you want to identify the provider by name (e.g., "google", "microsoft", "okta").

MFA Selection

When the site offers multiple MFA methods, they appear in mfa_options:

if (state.mfa_options?.length) {
  // Available types: sms, email, totp, push, call, password, switch
  for (const opt of state.mfa_options) {
    console.log(`${opt.type}: ${opt.label}`);
  }

  // Submit the selected MFA method
  await kernel.auth.connections.submit(auth.id, {
    mfa_option_id: 'sms'
  });
}

if state.mfa_options:
    # Available types: sms, email, totp, push, call, password, switch
    for opt in state.mfa_options:
        print(f"{opt['type']}: {opt['label']}")

    # Submit the selected MFA method
    await kernel.auth.connections.submit(
        auth.id,
        mfa_option_id="sms",
    )

if len(state.MfaOptions) > 0 {
	// Available types: sms, email, totp, push, call, password, switch
	for _, opt := range state.MfaOptions {
		fmt.Printf("%s: %s\n", opt.Type, opt.Label)
	}

	// Submit the selected MFA method
	_, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{
		SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{
			MfaOptionID: kernel.String("sms"),
		},
	})
	if err != nil {
		panic(err)
	}
}

After selecting an MFA method, keep listening for discovered_fields to submit the code, or handle external actions for push/security key.

The switch type represents generic method-switcher links like “Use another method” or “Try another way” that don’t name a specific factor. Submit it the same way as any other MFA option to reveal the underlying alternatives on the next page.

Some sites present non-MFA choices during login, such as account selection or organization pickers. These appear in sign_in_options as an array of objects with id, label, and optional description:

if (state.sign_in_options?.length) {
  // Show available options to the user
  for (const opt of state.sign_in_options) {
    console.log(`${opt.id}: ${opt.label}`);
    if (opt.description) console.log(`  ${opt.description}`);
  }

  // Submit the selected option
  await kernel.auth.connections.submit(auth.id, {
    sign_in_option_id: state.sign_in_options[0].id
  });
}

if state.sign_in_options:
    # Show available options to the user
    for opt in state.sign_in_options:
        print(f"{opt['id']}: {opt['label']}")
        if opt.get("description"):
            print(f"  {opt['description']}")

    # Submit the selected option
    await kernel.auth.connections.submit(
        auth.id,
        sign_in_option_id=state.sign_in_options[0]["id"],
    )

if len(state.SignInOptions) > 0 {
	// Show available options to the user
	for _, opt := range state.SignInOptions {
		fmt.Printf("%s: %s\n", opt.ID, opt.Label)
		if opt.Description != "" {
			fmt.Println("  " + opt.Description)
		}
	}

	// Submit the selected option
	_, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{
		SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{
			SignInOptionID: kernel.String(state.SignInOptions[0].ID),
		},
	})
	if err != nil {
		panic(err)
	}
}

Sign-in options are distinct from MFA options. MFA options (mfa_options) represent second-factor authentication methods like SMS or TOTP. Sign-in options represent non-security choices like “Which account do you want to use?” or “Select your organization.”

External Actions (Push, Security Key)

When the site requires an action outside the browser (push notification, security key tap), the step becomes AWAITING_EXTERNAL_ACTION:

if (state.flow_step === 'AWAITING_EXTERNAL_ACTION') {
  // Show the message to the user
  console.log(state.external_action_message);
  // e.g., "Check your phone for a push notification"

  // Some sites offer fallback methods alongside the external action
  // (e.g. "Try another way"). Submit one to switch verification methods.
  if (state.mfa_options?.length) {
    await kernel.auth.connections.submit(auth.id, {
      mfa_option_id: state.mfa_options[0].type,
    });
  }

  // Otherwise keep listening—the flow resumes automatically when the user completes the action
}

if state.flow_step == "AWAITING_EXTERNAL_ACTION":
    # Show the message to the user
    print(state.external_action_message)
    # e.g., "Check your phone for a push notification"

    # Some sites offer fallback methods alongside the external action
    # (e.g. "Try another way"). Submit one to switch verification methods.
    if state.mfa_options:
        await kernel.auth.connections.submit(
            auth.id,
            mfa_option_id=state.mfa_options[0]["type"],
        )

    # Otherwise keep listening—the flow resumes automatically when the user completes the action

if state.FlowStep == kernel.ManagedAuthFlowStepAwaitingExternalAction {
	// Show the message to the user
	fmt.Println(state.ExternalActionMessage)
	// e.g., "Check your phone for a push notification"

	// Some sites offer fallback methods alongside the external action
	// (e.g. "Try another way"). Submit one to switch verification methods.
	if len(state.MfaOptions) > 0 {
		_, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{
			SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{
				MfaOptionID: kernel.String(state.MfaOptions[0].Type),
			},
		})
		if err != nil {
			panic(err)
		}
	}

	// Otherwise keep listening—the flow resumes automatically when the user completes the action
}

mfa_options, pending_sso_buttons, and sign_in_options may be populated during AWAITING_EXTERNAL_ACTION when the site exposes fallback methods alongside the external action (for example, “Try another way” on a push prompt). Submit one of them to switch verification methods, or keep listening to let the user complete the external action.

Step Reference

The flow_step field indicates what the flow is waiting for:

Step	Description
`DISCOVERING`	Finding the login page and analyzing it
`AWAITING_INPUT`	Waiting for field values, SSO button click, SSO provider selection, MFA selection, or sign-in option selection
`SUBMITTING`	Processing submitted values
`AWAITING_EXTERNAL_ACTION`	Waiting for push approval, security key, etc.
`COMPLETED`	Flow has finished

Status Reference

The flow_status field indicates the current flow state:

Status	Description
`IN_PROGRESS`	Authentication is ongoing—keep listening
`SUCCESS`	Login completed, profile saved
`FAILED`	Login failed (check `error_message`)
`EXPIRED`	Flow timed out (10 minutes for user input, 20 minutes overall)
`CANCELED`	Flow was canceled

The status field indicates the overall connection state:

Status	Description
`AUTHENTICATED`	Profile is logged in and ready to use
`NEEDS_AUTH`	Profile needs authentication

Connection Configuration

Connection-level options — custom login URL, SSO/OAuth, custom proxy, session recording, post-login URL, and updates — apply equally to all integration flows and are documented in Connection Configuration.

SSE stream behavior

auth.connections.follow() opens the Server-Sent Events stream at:

GET /auth/connections/{id}/events

The stream delivers managed_auth_state events containing flow_status, flow_step, discovered_fields, and the other login-flow fields used throughout this guide. It closes automatically when the flow succeeds, fails, expires, or is canceled.

Use the SSE stream for login flows. It delivers state changes immediately and avoids repeated status requests.

Overview

Working with your browser

deploying your agent

Agent Skills

Integrations

Migrations

Community

Info

Programmatic Flow

How It Works

Getting started

1. Create a Connection

3. Stream and submit credentials

Complete Example

Handling Different Input Types

SSO Buttons

SSO Provider Selection

MFA Selection

External Actions (Push, Security Key)

Step Reference

Status Reference

Connection Configuration

SSE stream behavior

​How It Works

​Getting started

​1. Create a Connection

​2. Start a Login Session

​3. Stream and submit credentials

​Complete Example

​Handling Different Input Types

​SSO Buttons

​SSO Provider Selection

​MFA Selection

​Sign-In Options (Account/Org Pickers)

​External Actions (Push, Security Key)

​Step Reference

​Status Reference

​Connection Configuration

​SSE stream behavior

How It Works

Getting started

1. Create a Connection

2. Start a Login Session

3. Stream and submit credentials

Complete Example

Handling Different Input Types

SSO Buttons

SSO Provider Selection

MFA Selection

Sign-In Options (Account/Org Pickers)

External Actions (Push, Security Key)

Step Reference

Status Reference

Connection Configuration

SSE stream behavior