Skip to main content
status: preview KERNEL vaults group typed items that an attached browser can use. add a credential item for login or other non-payment credentials, or use provider-backed wallet and card items for payments. sensitive values aren’t returned by the vault api. use KERNEL’s fill api to safely inject stored values from supported items into browser fields without passing the values through your application’s injection code or model context. your controller supplies references and selectors; KERNEL writes the values and returns outcomes, not the values. invoke fill when the item advertises it in available_operations. for authentication workflows where your application or agent controls navigation and submission, start with Fill from Vault.
fill isn’t secret isolation from the browser. an agent with unrestricted browser access, page scripts, or extensions can read values after filling.
vaults are in preview. supported item types are credential, wallet, and card. available operations depend on the item type and current state. credential items currently don’t use a provider or wallet. for payment items, see wallet integrations.

​
How vaults work

​
Sensitive values do not come back through the api

sensitive values do not have a read path through the vault api. item responses return definitions, safe state, actions, and events. payment items can also return masks and/or aliases. credential fields marked sensitive: false return their populated values in state.fields. leave fields sensitive when they must remain write-only; set sensitive: false only when your backend or collection form needs to read and prefill an ordinary username or email address.

​
Use credentials from your existing vault

you can keep your existing vault as the source of truth. today, your trusted backend reads the values from that vault and copies them into a KERNEL credential item. KERNEL encrypts and stores that copy. the credential item becomes ready, and fill can write its fields into an attached browser without including their values in the fill request. the copy isn’t a live connection to your existing vault. when a credential changes there, update the KERNEL item before its next use. delete the item when your retention policy no longer permits KERNEL to hold the copy. in the future, a credential item might instead be backed by a third-party vault connection. that would follow the same resource pattern as a card item backed by a third-party wallet connection: the item remains the interface used by browser operations while the connection supplies the underlying material. third-party credential backing isn’t currently available.

​
Inject values with KERNEL’s fill api

retrieve the item and require fill in available_operations. your controller authorizes the destination and supplies field names and selectors, not the stored values. KERNEL checks the browser attachment and item lifecycle, validates the target inputs, and writes values into the attached browser. fill returns value-free per-field outcomes. it doesn’t submit a form or establish the site’s acceptance. inspect failed or unknown outcomes before taking another action; don’t automatically retry. see fill browser fields for the request and outcome contract. some integrations use a different operation or handoff. agentcard uses aliases and provider-executed checkout instead of fill; this is not a requirement for other vault items.

​
Vaults attach to browser sessions

attach one or more vaults when you create a browser. the binding cannot change for the life of the session and is enforced outside the browser vm. the binding is required for browser operations, including fill.

​
Resource model

​
Scope and attachment

select project scope on the sdk client or use a project-scoped api key. for direct api requests, X-Kernel-Project accepts a project id or name. project_id is not accepted in a vault request body. without explicit project scope, KERNEL uses the organization’s default project. attach vaults when you create a browser:
the vaults array supports up to 20 references. each reference accepts exactly one of id or name, and attachments cannot change after browser creation. a browser and vault must belong to the same project. attachment grants the browser access to the vault, not to a selected set of items. items created later in the same vault are available to every attached browser in that project. use separate vaults when browser tasks must not share access. deleting a vault or item prevents further use through that resource. it doesn’t undo values already filled into a browser or actions already performed by a site.

​
Api behavior

create or retrieve a vault by its immutable name. names accept 1–255 letters, numbers, ., _, and -, but can’t use a cuid-like value that could be mistaken for a vault id. vault responses contain id, name, created_at, and updated_at.
CLI
item keys are immutable and accept 1–255 letters, numbers, ., _, and -. creating an item at an existing key succeeds only when its type, specification, and provider, where applicable, match the existing item and its lifecycle permits retrieval. otherwise, the api returns a conflict. retrieve an item before acting on it. responses expose these fields and advertise what the current state permits: when action is present, complete it in a trusted user-facing surface. treat an action url as a short-lived bearer link: bind it to the authenticated user, vault, and item, and don’t log it. in application integrations, present the link directly to the user rather than putting it in model context. invoke only operations listed in available_operations, and request only expansions listed in available_expansions. don’t hard-code provider transitions from a previous response. item reads accept wait values from 0–60 seconds. payment reads return early when the item no longer has an unresolved authorization or approval transition. credential reads wait for readiness, not edits to an already-ready item; observe its version to detect changes. event reads support the same maximum wait and return an ordered array. use the last event id as the after cursor for newer events. deleting a vault invalidates every item and alias it contains. see the vaults api reference for endpoints and complete request and response schemas.

​
Payment items

payment items use the same vault resource model: a wallet connects a payment method through a provider, and a card represents payment material and authorization state. KERNEL’s fill api injects values from supported cards without returning them to your application or model. agentcard uses an alias-based alternative. see payments on KERNEL for the offering and lifecycle, then choose a wallet integration. for alias-based checkout, see agentcard’s lifecycle. for organization-scoped oauth client configuration, see wallet provider configurations. for wallet and card specifications, see the link and agentcard references. for actions and unresolved provider outcomes, see payment recovery.

​
Next steps