Credential Items

use a credential item for usernames, passwords, totp generators, and other non-payment credentials. it belongs directly to a vault; you don’t need a wallet or an external credential provider.

use wallet and card items for credit card numbers, security codes, and expiration dates. don’t store, collect, or fill payment-card data through credential items.

credential items store values and support explicit browser fill. your application or agent still handles navigation, submission, and the site’s response. choose managed auth instead when you want KERNEL to run login flows and maintain authenticated sessions.

Define an item

create a vault for each end user, then define their credential item. keep your api key and credential writes in your trusted backend. vault limits are organization-wide and depend on your plan. run kernel org entitlements -o json and inspect limits.max_vaults before choosing a per-user allocation strategy; null means unlimited. see organization entitlements.

import Kernel from "@onkernel/sdk";

const kernel = new Kernel({
  projectID: process.env.KERNEL_PROJECT_ID,
});
const vault = await kernel.vaults.upsert({ name: "user-12345" });
const item = await kernel.vaults.items.upsert("portal-login", {
  id_or_name: vault.id,
  type: "credential",
  spec: {
    description: "Account Portal",
    fields: {
      username: { type: "email", required: true, sensitive: false },
      password: { type: "password", required: true, sensitive: true },
    },
  },
});

import os

from kernel import Kernel

kernel = Kernel(
    project_id=os.environ["KERNEL_PROJECT_ID"],
)
vault = kernel.vaults.upsert(name="user-12345")
item = kernel.vaults.items.upsert(
    "portal-login",
    id_or_name=vault.id,
    type="credential",
    spec={
        "description": "Account Portal",
        "fields": {
            "username": {"type": "email", "required": True, "sensitive": False},
            "password": {"type": "password", "required": True, "sensitive": True},
        },
    },
)

use only the recognizable site or service name for description. it’s the collection form’s title, not a destination restriction. choose a vault per user or access boundary; don’t put unrelated users’ credentials in the same vault.

field setting	behavior
`type`	`text`, `email`, `password`, or `totp`
`required`	defaults to `true`; all required fields must have values for the item to become ready
`sensitive`	defaults to `true`; leave it `true` for write-only values, or set it `false` only when your backend or collection form needs to read and prefill the value
`value`	optional initial value from trusted code; omit it to leave the field unset

password and totp fields must be sensitive. usernames and email addresses can also remain sensitive; fill works either way. fields marked sensitive: false return their stored values in item responses. an item accepts 1–32 named fields. field names must start with an ascii letter, contain only ascii letters, numbers, and underscores, and be at most 64 characters. email values must be bare valid addresses such as user@example.com; use text for usernames that aren’t valid email addresses. initial values must be nonempty strings and fit within 16 kib of utf-8 data each; null and empty strings aren’t accepted on creation. field names, types, required flags, and sensitivity are immutable. repeating the same creation request retrieves the current item without overwriting later edits. use an update for value changes; use a new item key for a different field definition.

Copy values from an existing vault

if your application already stores a username and password in another vault, read them from your trusted backend and include each value in the initial upsert. this creates a ready item without opening a collection form. the example uses aws secrets manager, but the same flow applies to another vault. today, this operation copies the values into KERNEL rather than creating a live connection to the source vault. KERNEL encrypts and stores the copy. your existing vault can remain the source of truth, but changes there don’t automatically update the credential item.

import {
  GetSecretValueCommand,
  SecretsManagerClient,
} from "@aws-sdk/client-secrets-manager";

const secrets = new SecretsManagerClient({ region: "us-east-1" });
const source = await secrets.send(
  new GetSecretValueCommand({ SecretId: "production/account-portal" }),
);
if (!source.SecretString) {
  throw new Error("account portal credential is unavailable");
}
const credential = JSON.parse(source.SecretString) as Record<string, unknown>;
if (
  typeof credential.username !== "string" ||
  typeof credential.password !== "string" ||
  !credential.username ||
  !credential.password
) {
  throw new Error("account portal credential is incomplete");
}

const item = await kernel.vaults.items.upsert("portal-login", {
  id_or_name: vault.id,
  type: "credential",
  spec: {
    description: "Account Portal",
    fields: {
      username: {
        type: "email",
        required: true,
        sensitive: true,
        value: credential.username,
      },
      password: {
        type: "password",
        required: true,
        sensitive: true,
        value: credential.password,
      },
    },
  },
});
if (item.type !== "credential" || item.state.status !== "ready") {
  throw new Error("credential is not ready");
}

import json

import boto3

secrets = boto3.client("secretsmanager", region_name="us-east-1")
source = secrets.get_secret_value(SecretId="production/account-portal")
credential = json.loads(source["SecretString"])
if (not isinstance(credential.get("username"), str) or
        not isinstance(credential.get("password"), str) or
        not credential["username"] or not credential["password"]):
    raise RuntimeError("account portal credential is incomplete")

item = kernel.vaults.items.upsert(
    "portal-login",
    id_or_name=vault.id,
    type="credential",
    spec={
        "description": "Account Portal",
        "fields": {
            "username": {
                "type": "email",
                "required": True,
                "sensitive": True,
                "value": credential["username"],
            },
            "password": {
                "type": "password",
                "required": True,
                "sensitive": True,
                "value": credential["password"],
            },
        },
    },
)
if item.type != "credential" or item.state.status != "ready":
    raise RuntimeError("credential is not ready")

keep direct values in trusted backend variables and request bodies. don’t put them in frontend code, agent prompts, command-line arguments, logs, or traces. when the source credential rotates, use an authenticated update to copy the changed fields into the KERNEL item. repeating the initial upsert retrieves the existing item without overwriting its values. fill always operates on the ready credential item. a future provider integration might back that item with a third-party vault connection, similar to a card item backed by a third-party wallet connection. third-party credential backing isn’t currently available, so copying values is required today. continue with fill browser fields after the item is ready.

Collect values from the user

if required values are missing, the item has state.status: "pending_collection" and an action named collect. present action.url in your authenticated application, bound to the intended user and item. open the url as returned; don’t extract its token or pass it to the public item api.

collection links are bearer credentials. share them only with the intended user, not in shared logs, analytics, screenshots, or replay. in an application, present the link directly in the user’s authenticated interface. the cli cookbook lets an agent relay it in a private conversation. open collection outside the agent-controlled browser.

KERNEL-hosted links expire after 30 minutes. retrieve the item from your trusted backend to obtain a renewed link when needed; an expired link can’t renew itself. listing items doesn’t renew collection sessions. poll the item with a bounded wait until its status is ready. readiness means required values exist, not that a website accepted them. optional fields can remain unset, and unset fields can’t be filled. invoke the advertised collect operation to reopen collection for a ready item. this doesn’t clear its values. record its version before opening the form, then retrieve without wait to observe edits: wait waits for readiness, not changes to an already-ready item. a version change can also come from an api update, so it doesn’t identify a particular form submission. the form includes text, email, and password fields, not totp. non-sensitive values can be prefilled; stored secrets aren’t revealed. required visible inputs must be populated on submission.

Read and update values

spec.fields contains definitions, never initial values. state.fields reports has_value for each field. it also returns value when the field is populated and sensitive: false. sensitive values aren’t returned. updates require type: "credential" and the latest version. send only fields you want to change. bind forms to the immutable item id with expected_item_id so a deleted and recreated key can’t receive an old form’s submission.

const replacementPassword = process.env.NEW_PORTAL_PASSWORD;
if (!replacementPassword) {
  throw new Error("a replacement password is required");
}

const current = await kernel.vaults.items.retrieve(item.key, { id_or_name: vault.id });
if (current.type !== "credential" || current.id !== item.id) {
  throw new Error("credential item was replaced");
}
const updated = await kernel.vaults.items.update(item.key, {
  id_or_name: vault.id,
  type: "credential",
  version: current.version,
  expected_item_id: item.id,
  spec: { fields: { password: { value: replacementPassword } } },
});

replacement_password = os.environ["NEW_PORTAL_PASSWORD"]

current = kernel.vaults.items.retrieve(item.key, id_or_name=vault.id)
if current.type != "credential" or current.id != item.id:
    raise RuntimeError("credential item was replaced")
updated = kernel.vaults.items.update(
    item.key,
    id_or_name=vault.id,
    type="credential",
    version=current.version,
    expected_item_id=item.id,
    spec={"fields": {"password": {"value": replacement_password}}},
)

this replaces the password without returning either value. public updates can instead clear text, email, and password values with null or "", even when required; clearing a required value returns the item to pending_collection. required totp seeds can’t be cleared. this differs from the hosted form, which requires populated required inputs. a successful update increments the version and invalidates outstanding hosted collection sessions. on a 409 conflict, reload and reconcile with the user rather than automatically resubmitting stale edits.

Use totp

supply a base32 generator seed through trusted backend code, using value at creation or an authenticated update. a required totp field needs its seed at creation; the collection form can’t supply it. an optional totp field can receive its seed later. KERNEL generates a fresh six-digit code immediately before filling, using hmac-sha1 and a 30-second period. neither the seed nor a generated code is returned by item reads. the seed never enters the browser; the generated code does. custom algorithms, periods, and digit counts aren’t supported.

Build your own collection surface

your authenticated backend can retrieve safe item state and submit value updates using the ordinary item api. authenticate your own users, authorize their access to the vault and immutable item id, and apply the version precondition. keep broad KERNEL api credentials out of the frontend. render every form-supported field, omit totp, prefill only non-sensitive values, and don’t log submitted values. for an unchanged form, use your own completion callback rather than an empty update. KERNEL doesn’t store or authenticate your custom collection url. continue with fill browser fields or the browser agent cookbook.

Overview

Working with your browser

Integrations

Migrations

deploying your agent

Agent Skills

Community

Info

Credential Items

Define an item

Copy values from an existing vault

Collect values from the user

Read and update values

Use totp

Build your own collection surface

​Define an item

​Copy values from an existing vault

​Collect values from the user

​Read and update values

​Use totp

​Build your own collection surface

Define an item

Copy values from an existing vault

Collect values from the user

Read and update values

Use totp

Build your own collection surface