Fill from Managed Auth

Reuse a credential collected through Managed Auth to fill a login form in a browser your application controls

Managed Auth saves the durable fields a user enters during login, such as an email and password, so it can attempt eligible reauthentication later. A credential item backed by a Managed Auth connection lets your application reuse that saved credential with fill: your application or agent drives the login form in its own browser session, and Kernel writes the values, without collecting the credential a second time or returning it to your application.

The item stores no values of its own. It reads the connection’s saved credential each time you read the item or invoke fill, so a password updated through Managed Auth is used immediately.

fill only writes stored values into fields you select. It doesn’t discover fields, navigate, submit forms, verify authentication, monitor the session, or reauthenticate. Your application or agent owns each of those steps.

When to use it

Fill from Managed Auth works best when:

• your users already log in through Managed Auth with the Hosted UI, the React component, or the programmatic flow.
• a login prompt appears in a browser session that your application or agent controls, and you want to reuse the credential Managed Auth already holds.
• you want one credential per user, maintained by Managed Auth, instead of a second copy collected into a vault.

Choose Fill from Vault with a Kernel credential item when the credential isn’t collected through Managed Auth. Choose Managed Auth on its own when you want Kernel to run the login for you.

Requirements

• The connection holds a Kernel credential. Managed Auth saves one by default after a successful login. A connection created with save_credentials: false qualifies only if you linked a pre-stored credential when creating it.
• The connection’s credential is stored in Kernel. Connections backed by 1Password keep their values in 1Password and can’t back an item.
• The connection, the vault, and the browser belong to the same project.

How it works

These examples continue in order, using GitHub as the login destination. Set KERNEL_API_KEY in your trusted backend environment. All examples use the default project.

1. Log in through Managed Auth

   Create a connection and complete a login with the Hosted UI, the React component, or the programmatic flow. Managed Auth saves the fields the user entered once the login succeeds.

   TypeScript

   import Kernel from "@onkernel/sdk";
   
   const kernel = new Kernel();
   const auth = await kernel.auth.connections.create({
     domain: "github.com",
     profile_name: "user-12345-github",
   });
   const login = await kernel.auth.connections.login(auth.id);
   // Hand login.hosted_url, or login.id and login.handoff_code, to the user
   // and wait for the login to finish before continuing.
   

   Before continuing, confirm the connection holds a saved Kernel credential. The connection’s credential field names it once it’s saved:

   TypeScript

   const connection = await kernel.auth.connections.retrieve(auth.id);
   if (!connection.credential?.name) {
     throw new Error("managed auth hasn't saved a credential for this connection yet");
   }
   

   Wait for the saved credential, not for the connection’s status. A connection that’s NEEDS_AUTH still qualifies as long as it holds a saved credential.

2. Create the credential item from the connection

   Create a vault for the user, then create a credential item whose spec names the connection. The item is created ready, and state.fields lists the field names you can fill.

   TypeScript

   const vault = await kernel.vaults.upsert({ name: "user-12345" });
   const item = await kernel.vaults.items.upsert("github-login", {
     id_or_name: vault.id,
     type: "credential",
     spec: { provider: "managed_auth", connection_id: auth.id },
   });
   if (item.type !== "credential") throw new Error("expected a credential item");
   

   The request returns 404 when no connection has that id, and 409 when the connection hasn’t saved any credential values yet, belongs to another project, or is backed by an external provider such as 1Password. The 409 error names the condition. Fix the connection through the Managed Auth API, for example by finishing the login, then create the item again. Repeating the same request for an existing key returns the existing item.

3. Attach the vault to a browser

   Attach the vault when you create the browser. The attachment can’t change during the session and grants access to every item in the vault.

   TypeScript

   const browser = await kernel.browsers.create({ vaults: [{ id: vault.id }] });
   
4. Navigate and identify the login fields

   Your application or agent navigates to the login page and picks a selector for each field it wants filled. The selectors in the next step target GitHub’s login form; inspect the page and recheck them if it changes.

   TypeScript

   await kernel.browsers.playwright.execute(browser.session_id, {
     code: "await page.goto('https://github.com/login'); return await page.title();",
   });
   
5. Invoke the fill operation

   Retrieve the item, require ready and an advertised fill operation, then invoke fill with field names from state.fields and your selectors. Your application must authorize the destination before filling: fill doesn’t compare the page with the connection’s domain.

   TypeScript

   const current = await kernel.vaults.items.retrieve(item.key, { id_or_name: vault.id });
   if (current.id !== item.id || current.type !== "credential" ||
       current.state.status !== "ready" ||
       !current.available_operations.some((operation) => operation.type === "fill")) {
     throw new Error("credential is not ready to fill");
   }
   if (current.state.provider !== "managed_auth") throw new Error("expected a managed auth credential");
   // Bind by the names Managed Auth saved, for example ["email", "password", "totp"].
   console.log(Object.keys(current.state.fields));
   const result = await kernel.vaults.items.performOperation(item.key, {
     id_or_name: vault.id,
     type: "fill",
     browser_id: browser.session_id,
     page_url: "https://github.com/login",
     fields: [
       { field: "email", selector: "#login_field" },
       { field: "password", selector: "#password" },
     ],
   });
   if (result.type !== "fill" || result.status !== "completed") {
     throw new Error("stop and reconcile the fill outcome");
   }
   

   completed means the selected fields were filled, not that login succeeded. If fill fails, returns an uncertain outcome, or loses its response, stop and inspect the outcome rather than retrying automatically.

6. Submit and handle the response

   After fill completes, your application or agent submits the login form once and verifies the site’s response. If the site asks for an authenticator code and state.fields includes totp, navigate to that prompt and invoke fill again with a single totp binding, for example { "field": "totp", "selector": "#app_totp" } on https://github.com/sessions/two-factor/app. Kernel generates the code at fill time. Some sites submit the code as soon as it’s entered, so check the page state after the fill. Handle any other prompt through your own interface.

   Delete the demo browser when finished. Deleting the item later doesn’t affect the connection or its credential.

What the item exposes

Reading the item describes the credential without returning any values:

{
  "id": "credential_managed_auth_example",
  "key": "github-login",
  "type": "credential",
  "version": 1,
  "spec": {
    "provider": "managed_auth",
    "connection_id": "ma_abc123xyz"
  },
  "state": {
    "provider": "managed_auth",
    "status": "ready",
    "fields": {
      "email": { "type": "email" },
      "password": { "type": "password" },
      "totp": { "type": "totp" }
    }
  },
  "available_operations": [
    {
      "type": "fill",
      "description": "Fill selected fields from the connection's saved credential into a browser linked to this vault, without submitting."
    }
  ],
  "available_expansions": [],
  "created_at": "2026-01-01T12:00:00Z",
  "updated_at": "2026-01-01T12:00:00Z"
}

Field names come from the login itself, so read them from state.fields instead of assuming them. Each entry carries a type of text, email, password, or totp. A totp entry appears when the credential includes a TOTP secret; fill writes a freshly generated code for it and never the secret. Entries change when the connection’s credential changes, and the item’s version stays at 1, so compare state.fields rather than version to observe changes.

Item status

Kernel computes the item’s status each time you read it, from the connection it points at.

state.status	state.status_reason	Meaning
ready		The connection’s saved credential can be read and fill is advertised. It doesn’t mean a login succeeded.
unavailable	no_credential	The credential was deleted or emptied after the item was created.
unavailable	connection_not_found	The connection was deleted.
unavailable	external_credential	The connection now uses an external credential provider.

An unavailable item advertises no operations. Managed Auth owns the connection and its credential, so recover through the Managed Auth API. For no_credential and external_credential, start a new login or relink a Kernel credential; once the connection holds a saved Kernel credential again, the item reads it and reports ready without being recreated. For connection_not_found, the item can’t recover, because its connection_id is fixed: delete it and create a new item for the replacement connection.

How it differs from a Kernel credential item

• There’s no collection form and no collect operation. Managed Auth collects the login.
• The item can’t be edited. Change the credential through Managed Auth, by logging in again or updating the linked credential, and the item picks the change up.
• Field names and types mirror the saved credential instead of a field list you declare. wait doesn’t apply, because the item is created ready.
• Deleting the item leaves the connection and its credential in place. Deleting the connection or its credential makes the item unavailable.

Security boundary

fill writes real values into the browser. Page scripts, extensions, developer tools, and an agent with unrestricted browser access can read them afterwards. Attaching a vault grants a browser access to all of its items, so attach it only to sessions authorized to use every item, and keep fill requests in your trusted backend. fill doesn’t restrict credential items to the connection’s domain, so authorize the destination in your application before invoking it.

Next steps

Fill Browser Fields

Map credential fields to browser inputs and handle completed, failed, or unknown outcomes.

Managed Auth Credentials

How Managed Auth saves credentials during login and how to update them.

Connection Lifecycle

Health checks, reauthentication, and recovering a connection that needs input.