vaults are in preview. the initial release supports
wallet and card items
for stripe link 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 values do not have a read path through the vault api. item responses return non-sensitive specifications, state, masks, aliases, actions, and events, but not the underlying value. for the initial payment integrations, a provider-hosted flow collects the user’s payment method and the provider-backed card reaches the vault without passing 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. 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. stripe 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. stripe 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 stripe link and agentcard provider guides.Initial item specifications
the initial release accepts thesespec fields. fields not listed here are rejected.
Wallets
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 - agentcard:
requested,ready,pending_approval,degraded
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.