vaults are in preview. the initial release supports
wallet and card items
for link by stripe and
agentcard. here, provider means the
credential provider connected to the vault, not the merchant’s payment
processor. the vault model isn’t limited to payments, but no other item types
or credential providers are supported in this release.How vaults work
Values do not come back through the api
sensitive payment values do not have a read path through the vault api. item responses return specifications, state, masks, aliases, actions, and events, but not the underlying value. for link, KERNEL stores oauth credentials and approved one-use card data with kms-backed envelope encryption. for agentcard, the underlying card remains with agentcard. both providers connect the user’s payment method through a hosted flow, without passing card data through your application or agent.Agents use aliases
each item can publish non-sensitive, format-valid aliases. in the initial release, a card item can return a luhn-valid 16-digit number, a three-digit cvc, and an expiry month and year. these values pass client-side checkout validation but cannot resolve unless the browser session and vault are bound together.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 agent uses aliases like any other form input.Substitution happens at egress
the KERNEL egress layer runs outside the browser vm. when it recognizes a request containing an alias, it verifies the browser, session, project, vault, item, and provider state before resolving the provider-backed value. the browser receives the destination’s response without receiving that value. resolution fails closed when any binding or state check does not match.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:
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 invalidates its provider-backed values and aliases.
Api behavior
create or retrieve a vault by its immutablename. 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
., _, and -. creating an item at an existing key succeeds only when its type, provider, and specification 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 or put 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. a read returns early when the item no longer has an unresolved authorization or approval transition. 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.
Payments first
the initial release applies the vault primitive to browser checkout. a wallet connects an end user’s payment method through a provider-hosted flow. a card item then publishes aliases that an attached browser can enter into a web checkout. authorization and payment handoff happen outside the browser vm. link and agentcard are credential providers, not merchant payment processors. at the browser form layer, both work with any web checkout that accepts standard card details, and the merchant’s processor doesn’t need to be stripe. end-to-end handoff requires the outgoing request to match a native processor adapter. the current adapters cover request formats used by stripe, shopify, square, recurly, and razorpay; see checkout and processor coverage. link creates a one-use card for an approved purchase. agentcard keeps a reusable card item and requests approval for each checkout. wallet connection, authorization, provider handoff, and checkout observations are recorded as immutable events without card data. read the payments overview for the shared lifecycle or use the link by stripe and agentcard provider guides.provider configurations
use KERNEL-managed credentials by default. if you need your own client, follow the optional setup in link or agentcard. a named provider configuration stores your application’sclient_id and client_secret,
not an end user’s wallet grant. credentials are encrypted at rest; secrets are
never returned.
configurations are organization-scoped and shared across projects, unlike
project-scoped vaults. create, update, and delete require organization-scoped
authentication; project-scoped api keys receive 403. names are unique within
the organization, and duplicate creates return 409 without replacing secrets.
- selection: choose exactly one config
idornamewhen creating a wallet. the cli accepts--provider-config-idor--provider-config-name; responses resolve names to ids. - binding: the wallet’s configuration is immutable, and cards inherit it. renaming a config preserves bindings.
- rotation: updating
client_secretaffects all bound wallets. provider, client id, and agentcard mode cannot change; changing clients requires a new config and new wallets. - deletion: returns
409while any non-deleted item references the config, even if disconnected. it does not delete the external oauth client or revoke unrelated grants. - recovery:
recovery_requiredmeans a card’s provider outcome is unresolved. it stops item wait loops and blocks new authorization, checkout, and deletion of the card or its parent wallet/vault.
Initial item specifications
the initial release accepts thesespec fields. fields not listed here are rejected.
Wallets
the default link client is
{type: 'kernel_managed'}. for your own client, set
authorization.client to {type: 'customer_managed', provider_config: {name: 'checkout-link'}}
and supply authorization.tokens with access_token and refresh_token.
for payment settings ui, enforce at most one wallet per provider in each vault.
the api currently enforces uniqueness by item key, not by wallet provider, so a
different key can create a second wallet for the same provider. list items before
rendering provider options, hide the add option whenever that provider already
has a wallet in any state, and reuse or recover the existing item.
Cards
a card’s
spec.wallet must reference a wallet in the same vault and from the
same provider.
amount uses minor currency units. link accepts 1–500000, requires a three-letter currency, limits merchant_name to 255 characters, requires an absolute http or https merchant_url, and requires at least 100 characters in context. its optional expires_at is a unix timestamp in seconds.
agentcard accepts amounts from 1–9007199254740991 and a three-letter currency. merchant accepts 1–120 printable characters without control characters. card_id uses the provider’s vc_ identifier, and wallet user_id uses its usr_ identifier.
link line_items support name, quantity, unit_amount, description, sku, url, image_url, product_url, and totals. each totals entry supports type, display_text, and amount. link metadata accepts string values.
card updates replace the complete spec; they are not partial merges. link card items can update only while requested. agentcard card items can update while requested or ready, but not while approval is pending.
deleting a card consumes its aliases and clears any stored provider value.
deleting a wallet also invalidates its dependent cards.
Initial payment actions, states, and aliases
action.name can be link_oauth, spend_approval, push_approval, collect, mfa, embedded_ceremony, or card_enrollment. actions that require a hosted interaction include a url. don’t send action urls or provider authorization material to the agent.
wallet status values are:
- link:
pending_authorization,connected,declined,reconnect_required,degraded - agentcard:
pending_authorization,connected,degraded
- link:
requested,pending_authorization,ready,consumed,expired,declined,recovery_required - agentcard:
requested,ready,pending_approval,degraded,recovery_required
masks.brand, masks.last4, and read-only aliases: number, cvc, exp_month, and exp_year. aliases are non-sensitive stand-ins, not standalone credentials or permission to use the provider-backed value.