---
title: "Perform an operation advertised by a vault item"
method: POST
path: "/vaults/{id_or_name}/items/{key}/operations"
tags: ["Vaults"]
---

# Perform an operation advertised by a vault item

`POST /vaults/{id_or_name}/items/{key}/operations`

## Request

- Base URL: `https://api.onkernel.com`
- URL: `https://api.onkernel.com/vaults/{id_or_name}/items/{key}/operations`
- Auth: HTTP bearer

Retrieve the item first and invoke only an operation listed in
`available_operations`, following its natural-language description.
Availability is rechecked at execution time; unavailable operations return 409.
Authorization and preparation may call an external provider and return updated state.
Link cards advertise authorize; pass browser_id and page_url from the final
checkout page so Kernel can inspect the checkout. Eligible unused
AgentCard cards advertise prepare_checkout, which requires checkout context
and obtains device approval before native Square Pay. Keep the returned
approval page open, poll until ready_to_submit, then submit before
preparation.expires_at. Unused preparations expire automatically and cannot
be reused. If spend-request creation is rejected with a non-retryable
provider error, the card item is deleted and the provider's error code and
message are returned. Rate limits return HTTP 429 and retain the card item;
stop, back off, and retry the same authorize operation.

Ready Kernel cards advertise fill. Fill delivers card details for a few
minutes; submit checkout promptly after filling. A repeated fill is safe.

Fill returns a value-free execution result. Validation failures before
writing return 400 (invalid request or targets), 403 (access or destination
denied), 404 (resource not found), or 409 (item or browser not ready).
Once writing starts, known partial failures and indeterminate field outcomes
return 200 with status `failed` or `unknown`. Fill never submits the page, so
it is safe to retry after a failure, an `unknown` outcome, or a transport error.

Connected Kernel wallets may advertise add_payment_method, which returns a
single-use hosted card_enrollment link for a card, and
remove_payment_method, which removes one card without affecting the others.
Both operations require vaults:write in addition to vaults:use on the vault
for scoped API keys, and return 403 without both permissions.

## Path parameters

- `id_or_name` string, required
- `key` string, required

## Request body

- union
  - AuthorizeVaultItemOperationRequest: Authorize a Link, Kernel or Shop Pay card using its existing purchase specification. Use only after explicit user approval and when the item advertises authorize; follow the advertised operation's description. For a Link or Shop Pay card, pass browser_id and page_url together while the browser is on the final checkout page: Kernel confirms that checkout is open, sends it to the provider as the merchant, and limits fill to that checkout's origin in any browser with this vault attached. For Link it also chooses how the credential is delivered. Omitting both issues a virtual card that fills any page on the merchant origin. Once approval has been requested, browser_id and page_url are ignored and authorize only re-checks the request. Browser and checkout inspection errors occur before any provider request and can be retried once the browser is on the checkout page. Kernel cards do not accept browser_id or page_url.
    - `browser_id` string: Browser session ID, not a reusable browser name. The browser must have this vault attached.
    - `page_url` string, uri: Exact current top-level URL of the final checkout page open in browser_id.
    - `type` 'authorize', required
  - RestartVerificationVaultItemOperationRequest: Explicitly prepare a fresh local verification session for the same Kernel Visa purchase and connected wallet, only when restart_verification is advertised. Kernel must have durable proof of an initial attestation failure before intent dispatch. Replaces the spend_approval capability and discards session-bound verification data without calling the provider or granting spend consent. The cardholder must use the new link, verify again and explicitly approve the purchase. Unknown intent creation, legacy unclassified recovery, enrollment completion, issuance and confirmation cannot restart. Do not automatically retry this operation.
    - `type` 'restart_verification', required
  - ConfirmTransactionVaultItemOperationRequest: Report a real merchant transaction outcome for an issued Kernel Visa or Shop Pay credential. Shop Pay accepts PURCHASE, AUTHORIZATION and CAPTURE. Never infer success from filling checkout or receiving a credential. Supply the observed status, transaction type, actual amount, currency and timestamp. Unknown outcomes require manual reconciliation, not retry. Each purchase accepts one report.
    - `amount` integer, required: Actual transaction amount in minor units, no greater than the approved limit.
    - `currency` string, required: Must match the approved purchase currency.
    - `failure_code` string: Why the purchase did not succeed, for any other outcome, such as 3ds_challenge, captcha, login_required, timeout or site_error. payment_declined goes only with DECLINED, which takes no other code. Shop Pay reports it; other providers ignore it.
    - `occurred_at` string, date-time, required: Time the merchant outcome was observed.
    - `order_id` string: The merchant's order number, for an APPROVED outcome. Shop Pay reports it; other providers ignore it.
    - `order_url` string, uri: The merchant's https order page, for an APPROVED outcome. Shop Pay reports it; other providers ignore it.
    - `status` 'APPROVED' | 'DECLINED' | 'PENDING' | 'ERROR' | 'CANCELLED', required
    - `transaction_type` 'PURCHASE' | 'AUTHORIZATION' | 'CAPTURE' | 'REFUND' | 'REVERSAL' | 'VERIFICATION' | 'CHARGEBACK' | 'FRAUD', required
    - `type` 'confirm_transaction', required
  - CollectVaultItemOperationRequest: Return the credential item with its collection action. Supported for ready and pending_collection credential items. Always render the same form from every form-supported field; totp and passkey fields have no form input and are omitted. No caller-selected field subsets or form overrides are accepted. Reuse an active Kernel-hosted session or renew an expired session atomically. Customer-hosted forms use their own backend and ordinary item GET/PATCH. Opening the form does not clear values or change readiness or item version. To observe edits on a ready item, record its version and poll GET without wait until the version changes, then reconcile the returned state. Version changes may also come from PATCH; they do not identify a particular form submission. Customer-hosted apps use their own submission callback, including for unchanged forms. The wait parameter waits for readiness, not edits.
    - `type` 'collect', required
  - PrepareCheckoutVaultItemOperationRequest: Prepare an unused AgentCard card for a supported checkout. Deliver the returned approval URL and keep the approval page open. Poll the item until ready_to_submit, then submit native Pay before preparation.expires_at. Readiness lasts at most 30 seconds. Unused preparations expire automatically. Preparations are single-use even after failure or expiry; do not automatically retry and reconcile uncertain outcomes with the merchant.
    - `checkout` VaultCheckoutContext, required: Required when preparing an unused AgentCard card for a supported checkout processor. Consent is bound to this browser and declared merchant origin, not a tab. Wait for the item's ready_to_submit status before native Pay and submit within its readiness deadline. Unused preparations expire automatically; every preparation is single-use, including after failure or expiry.
      - `browser_id` string, required: Active browser session with this vault bound to it.
      - `environment` 'production' | 'sandbox' | 'shared', required: Use production or sandbox for Square, Braintree, Worldpay and Adyen; shared for Bambora and Mercado Pago. Shared endpoints do not establish test mode. Merchant credentials/configuration determine processor test mode, independently of the AgentCard credential mode.
      - `merchant_origin` string, required: Canonical HTTPS origin of the top-level merchant document, not a processor iframe. HTTP localhost is accepted for tests.
      - `psp` 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago' | 'adyen'
    - `type` 'prepare_checkout', required
  - FillVaultItemOperationRequest: Use a vault item in a browser session, for example to fill a login or payment form. Only invoke when the item advertises `fill`; the advertised operation describes the inputs that item needs. Requires `browser_id` and usually `page_url`; some items also require `fields`. Browser and vault must belong to the same project. Kernel checks access and allowed destinations before filling; providing a page URL does not authorize a destination. Fill never submits forms or clicks buttons, though input and change events may trigger site behavior. It is not atomic: completed steps are not rolled back. Fill does not consume the item, so a failed or indeterminate fill is safe to retry. A retry right after an indeterminate fill may wait up to 15 seconds for the earlier attempt's browser lock to expire. Secret values are never returned or included in operation logs, traces, audit events, or error details. This does not prevent an agent with unrestricted browser access from reading values from the page or other browser observation surfaces.
    - `browser_id` string, required: Browser session ID, not a reusable browser name.
    - `fields` VaultFillField[]: Field bindings, when the item's advertised fill operation requires them. Each selector is searched in the main frame and all descendant frames and must resolve to exactly one editable input or select, matched directly or through a containing element; zero or multiple candidates fail, and no two bindings may resolve to the same element. Select elements match an option by value, not label. All bindings are validated before any write, then filled in request order, stopping at the first failure. If the page navigates or a target disappears, fill stops rather than choosing another page or element.
      - `field` string, required: A credential field name from the item's declared fields (Kernel) or state.fields from a single-item read (managed auth), or a supported card field. Unset credential fields cannot be filled.
      - `format` 'MM/YY' | 'MM/YYYY': Required only for a card's combined expiration field. Forbidden for other card fields and all credential fields.
      - `selector` string, required
    - `page_url` string, uri: Exact current top-level page URL, including path, query, and fragment. Must match exactly one open page in the browser; zero or multiple matches fail. No prefix or glob matching. When an item allows omitting it, the browser must have exactly one open page.
    - `timeout_ms` integer: Ignored. Fill sets no operation deadline; typing pace adapts to the length of the values instead. Accepted for compatibility.
    - `type` 'fill', required
  - ArmPasskeyVaultItemOperationRequest: Let a browser attached to the item's vault sign in with a stored passkey. Only invoke when the item advertises `arm_passkey`. Returns immediately; there is no time limit. While armed, when a page in that browser whose origin matches the passkey's relying party asks for a passkey (`navigator.credentials.get`, including autofill requests made at page load), Kernel answers with this passkey. The private key never enters the browser: Kernel signs on its servers, using the origin Chrome reports for the requesting frame. Arming a passkey for a relying party replaces any passkey armed earlier in the browser for the same relying party. The arm lasts until `disarm_passkey`, the browser ends, the vault is detached, or the item or field is deleted. Drive the sign-in with your own browser tools and inspect the page to confirm it. A page opened in a new tab or window can run its first scripts before Kernel's handler attaches; if such a page asks for a passkey as soon as it loads, reload it. While armed, any script running on the relying party's pages can obtain a sign-in without user interaction, as with a password manager that fills automatically; disarm when the task is done. Passkeys report a signature counter of 0 and backup flags, as synced passkeys do.
    - `browser_id` string, required: Browser session ID, not a reusable browser name.
    - `field` string: Passkey field to arm. Required when more than one passkey field holds a passkey.
    - `type` 'arm_passkey', required
  - RegisterPasskeyVaultItemOperationRequest: Let a browser attached to the item's vault create a passkey on a website and store it in an empty passkey field. Only invoke when the item advertises `register_passkey`; declare the field first, for example by adding an optional passkey field with a credential update. Returns immediately; there is no time limit. The next passkey a page in that browser creates (`navigator.credentials.create`) is generated by Kernel, stored in the field, and only then returned to the page, so the website never receives a passkey Kernel failed to store. Each browser has one pending registration; a later `register_passkey` replaces it. Drive the website's "add a passkey" flow with your own browser tools, then confirm by reading the item (the field reports `has_value`) or its `credential_passkey_registered` event, and by signing in with `arm_passkey`. Only ES256 passkeys are created.
    - `browser_id` string, required: Browser session ID, not a reusable browser name.
    - `field` string: Empty passkey field to store the new passkey in. Required when more than one passkey field is empty.
    - `type` 'register_passkey', required
  - DisarmPasskeyVaultItemOperationRequest: Stop a browser from using this item's passkeys: removes its armed passkeys and its pending registration into this item. Pages that already loaded keep Kernel's WebAuthn handler but get the browser's own behavior.
    - `browser_id` string, required: Browser session ID, not a reusable browser name.
    - `field` string: Limit disarming to one passkey field. Omit to disarm every passkey field of the item.
    - `type` 'disarm_passkey', required
  - OnePasswordRequestAccessVaultItemOperationRequest: Request access to login entries in the end-user's own, non-shared 1Password vault. No browser is needed; the end-user approves access in the 1Password app. Shared-vault items and passkeys are not supported. Per-entry reason and keywords overrides are only supported for a single login entry.
    - `goal` string
    - `keywords` string[]
    - `reason` string
    - `type` '1pw_create_access_request', required
  - OnePasswordPollAccessVaultItemOperationRequest: Retrieve the status of a 1Password access request after presenting the approval link. On a confirmed failed status, ask the end-user before deleting and recreating the credential item for at most one new request. Do not retry an uncertain dispatched request. The response contains no secret values. Credentials with a customer-supplied access token also return the granted references in state.access_request.resolved.
    - `timeout_seconds` integer
    - `type` '1pw_access_request_status', required
  - OnePasswordFillVaultItemOperationRequest: Fill and submit an approved 1Password login in the selected browser page. The page must share the selected entry's login origin. Supply entry_id when more than one approved entry matches the page origin, and target_id when more than one open page has page_url. The extension selects fields; callers cannot supply selectors or secret values. Submission does not confirm website authentication.
    - `browser_id` string, required: Browser session ID, not a reusable browser name.
    - `entry_id` string: ID of an approved request entry. Required when several approved entries have the page's origin.
    - `page_url` string, uri, required: Exact current top-level page URL. Must match exactly one open page in the browser unless target_id is supplied.
    - `target_id` string: CDP target ID of the page to fill, such as tab.target_id from playwright.execute. Use it when several open pages have page_url. The page's current URL must equal page_url. Kernel brings the page to the front of its window before filling.
    - `timeout_ms` integer
    - `type` '1pw_fill', required
  - OnePasswordRecoverVaultItemOperationRequest: Kernel encountered a recoverable error while linking this 1Password account. Use this action to get a new link to recover the connection. After recovery completes, start a new authorization on the same item.
    - `type` '1pw_recover', required
  - OnePasswordUpdateAccessTokenVaultItemOperationRequest: Replace only the access token on a stored-token 1Password credential. Preserves its integration key, request and approved references. Does not invoke 1Password or retry a pending/uncertain operation.
    - `access_token` string, required
    - `access_token_expires_at` string, date-time: Optional supplied expiry. Omit to clear the old expiry.
    - `type` '1pw_update_access_token', required
  - WebMCPInvokeVaultItemOperationRequest: Invoke a WebMCP tool using values from a vaulted item. The browser must be attached to the item's vault. Discover the tool_ref, inputSchema, and source with GET /browsers/{id_or_name}/webmcp/tools or webmcp.listTools() in the Browser REPL (POST /browsers/{id_or_name}/repl) before invoking it. Input paths replace existing null slots in input. Tool output is returned without redaction and may include the supplied values. The tool may submit or perform other side effects. Any item destination restrictions apply to the tool's top-level page and registering frame (if any).
    - `bindings` VaultWebMCPBinding[], required
      - `field` string, required: A declared, populated credential field or supported card field. A TOTP field supplies a fresh code, never its seed. Passkey fields cannot be filled.
      - `format` string: Required for card expiration (MM/YY or MM/YYYY), forbidden for other fields. Invalid formats are rejected before invocation.
      - `input_path` string, required: RFC 6901 JSON Pointer to an existing null value in input. Object keys are exact; array indices must be canonical and in range. No root or array-append paths. Each path and each field may occur only once.
    - `browser_id` string, required: Browser session ID, not a reusable browser name.
    - `input` object, required: Public tool arguments with an existing null slot at each binding path. At most 64 KiB after JSON serialization, including substituted values. Never include vault values here.
    - `page_url` string, uri, required: Exact top-level URL from the discovered tool source (fragment omitted). This pins the target page; it does not authorize a destination.
    - `timeout_sec` integer: Tool invocation timeout in seconds; preflight and response handling have an additional bounded allowance. An indeterminate outcome is not retried.
    - `tool_ref` string, required: Opaque reference to the exact live WebMCP registration.
    - `type` 'webmcp_invoke', required
  - AddPaymentMethodVaultItemOperationRequest: Start hosted enrollment of a card in a connected Kernel wallet, including its first card, only when the wallet advertises add_payment_method. Returns a new payment method in pending_enrollment with a single-use card_enrollment URL for the cardholder. Card details go directly to the card vault and are never accepted by this API. Each call creates a separate link that expires after 30 minutes; a failed or expired enrollment does not affect the wallet's other payment methods. Scoped API keys require vaults:write in addition to vaults:use on this vault; otherwise the operation returns 403.
    - `type` 'add_payment_method', required
  - RemovePaymentMethodVaultItemOperationRequest: Remove one payment method from a Kernel wallet, only when the wallet advertises remove_payment_method. Removal deletes the stored card and blocks new purchases, fills and confirmations funded by it without affecting the wallet's other payment methods; the wallet stays connected even with no payment methods left. A purchase funded by the method with an unresolved outcome blocks removal with 409 purchase_unresolved. If the provider outcome is uncertain the method stays in removal_pending and keeps refusing payments; retry the removal later. Removal is not proof that a payment did not occur. Scoped API keys require vaults:write in addition to vaults:use on this vault; otherwise the operation returns 403.
    - `payment_method_id` string, required: ID from the wallet's payment_methods expansion.
    - `type` 'remove_payment_method', required

## Response `200`

Authorization or preparation completed or resumed, or fill execution outcomes returned

- union: Authorization and preparation return the existing item shape. Fill and passkey operations return value-free results; WebMCP invocation returns the tool's output. None persist transient outcomes on the item. Payment-method operations return the affected wallet payment method.
  - union
    - WalletVaultItem
      - `action` union
        - LinkOAuthAction
          - `name` 'link_oauth', required
          - `url` string, uri, required
        - ShopPayOAuthAction
          - `name` 'shop_pay_oauth', required
          - `url` string, uri, required: Shop sign-in page where the shopper connects their Shop account to Kernel.
        - OnePasswordOAuthAction
          - `name` '1password_oauth', required
          - `url` string, uri, required: 1Password-hosted OAuth authorization URL for the human to open.
        - SpendApprovalAction
          - `name` 'spend_approval', required
          - `url` string, uri, required
        - PushApprovalAction
          - `name` 'push_approval', required
        - CollectAction
          - `name` 'collect', required
        - MfaAction
          - `name` 'mfa', required
        - EmbeddedCeremonyAction
          - `name` 'embedded_ceremony', required
        - CardEnrollmentAction
          - `capture_token` string: Secret bearer capability for embedded card capture with @onkernel/vault-react. Present only for Kernel wallets; never for AgentCard. Treat it like the enrollment URL and do not log or persist it in browser storage.
          - `name` 'card_enrollment', required
          - `url` string, uri, required
      - `available_expansions` AvailableVaultItemExpansion[], required
        - `description` string, required
        - `type` 'payment_methods' | 'link_user_info' | 'link_shipping_addresses', required
      - `available_operations` AvailableVaultItemOperation[], required
        - `description` string, required
        - `type` 'authorize' | 'restart_verification' | 'confirm_transaction' | 'collect' | 'prepare_checkout' | 'fill' | 'arm_passkey' | 'register_passkey' | 'disarm_passkey' | '1pw_create_access_request' | '1pw_access_request_status' | '1pw_fill' | '1pw_recover' | '1pw_update_access_token' | 'webmcp_invoke' | 'add_payment_method' | 'remove_payment_method', required
      - `created_at` string, date-time, required
      - `description` string: Server-generated provider and lifecycle guidance for agents.
      - `expanded` VaultItemExpanded: Live, non-persisted data requested through the item GET expand parameter.
        - `link_shipping_addresses` LinkShippingAddress[]: Link's saved shipping addresses, present when the `link_shipping_addresses` expansion is requested.
          - `address` LinkShippingAddressDetails: Link's nullable postal address fields. Omitted from the shipping address when Link reports null.
            - `administrative_area` string, nullable, required: State, province or region.
            - `country_code` string, nullable, required
            - `dependent_locality` string, nullable, required
            - `line_1` string, nullable, required
            - `line_2` string, nullable, required
            - `locality` string, nullable, required: City or town.
            - `name` string, nullable, required
            - `postal_code` string, nullable, required
            - `sorting_code` string, nullable, required
          - `id` string, required: Link shipping address ID.
          - `is_default` boolean, required
          - `nickname` string, nullable, required
        - `link_user_info` LinkUserInfo: Link's `GET /userinfo` response for the connected wallet, passed through as Link reports it when the `link_user_info` expansion is requested. Kernel never stores it. Null fields are null at Link; omitted fields were not reported. Amounts are in the minor unit of `default_spend_request_currency`.
          - `address` LinkUserInfoAddress: The Link user's postal address. Omitted when Link reports none.
            - `city` string, nullable, required
            - `country` string, nullable, required
            - `line1` string, nullable, required
            - `line2` string, nullable, required
            - `postal_code` string, nullable, required
            - `state` string, nullable, required
          - `agent_wallet_spend_limits` LinkAgentWalletSpendLimits: Link's agent wallet spend limits, per transaction and over rolling periods.
            - `daily` LinkRollingSpendLimit, required
              - …
            - `per_transaction` LinkSpendLimit, required
              - …
            - `thirty_day` LinkRollingSpendLimit, required
              - …
          - `agent_wallet_step_up` LinkAgentWalletStepUp: Verification Link requires from the user before the agent wallet can spend.
            - `action_url` string, nullable, required: URL where the user completes verification; null when no action is available.
            - `status` string, required: Link status such as not_required, ssn_verification, identity_verification, contact_support or complete.
          - `default_spend_request_currency` string: Lowercase ISO currency Link applies to a spend request created without one.
          - `eligible_for_balance` boolean: Whether the user can fund purchases from a Link balance.
          - `email` string, nullable, required
          - `first_name` string, nullable, required
          - `id` string, nullable, required: Stable Link user ID.
          - `last_name` string, nullable, required
          - `name` string, nullable, required
          - `phone` string, nullable, required
        - `payment_methods` VaultPaymentMethod[]
          - `action` CardEnrollmentAction
            - `capture_token` string: Secret bearer capability for embedded card capture with @onkernel/vault-react. Present only for Kernel wallets; never for AgentCard. Treat it like the enrollment URL and do not log or persist it in browser storage.
            - `name` 'card_enrollment', required
            - `url` string, uri, required
          - `capabilities` VaultPaymentMethodCapabilities, required: Provider-reported advisory capabilities. A missing capability is unknown, not ineligible; only eligible=false is an explicit negative signal.
            - `single_use_card` VaultPaymentMethodCapability
              - …
          - `display` VaultPaymentMethodDisplay, required
            - `brand` string
            - `label` string
            - `last4` string
          - `expires_at` string, date-time: Expiry of a pending enrollment link.
          - `id` string, required
          - `is_default` boolean, required: For Kernel wallets, true for the default card, ID card, which a Kernel card item that omits payment_method_id selects. Wallets created with payment methods enabled have no default card.
          - `provider` string, required: Provider that issued this payment-method ID.
          - `status` 'pending_enrollment' | 'active' | 'removal_pending' | 'recovery_required': Kernel wallets only. pending_enrollment means a card_enrollment link is open; active means the card is stored and can pay when capabilities.single_use_card.eligible is true; removal_pending means removal started but the provider outcome is unknown, so retry remove_payment_method; recovery_required means either an enrollment outcome is unknown (remove the method), or the stored card cannot be read (contact support; removal is refused with 409). Consult status_reason to distinguish these cases. Absent for other providers.
          - `status_reason` string
          - `type` string, required: Provider-neutral payment-method type normalized to lowercase.
      - `expires_at` string, date-time
      - `id` string, required
      - `key` string, required: Immutable item key assigned when the item is created.
      - `spec` union, required
        - LinkWalletVaultItemSpec
          - `authorization` LinkOAuthAuthorization, required
            - `client` union, required
              - …
            - `method` 'oauth', required
          - `provider` 'link', required
        - AgentCardWalletVaultItemSpec: AgentCard wallet. Omit provider_config to use Kernel-managed credentials, or select a customer-owned configuration. Mode (sandbox vs live) is determined by the selected credential; there is no per-item test flag. Without user_id, creation returns a hosted enrollment action and Kernel polls until the user connects. With a customer-owned provider_config, user_id imports an existing connection after verifying access with the selected credentials in their sandbox or live mode; no hosted enrollment is needed, even if the connected user has no stored cards. With Kernel-managed credentials, user_id may only reference a user already enrolled by a wallet in this organization under the same configuration. The user and configuration bindings cannot be changed after creation. Import validation is read-only and runs before creation: a failed validation leaves no wallet or reserved key, so the user_id can be corrected and retried. Concurrent imports of the same key may both validate, but create at most one wallet and connected event.
          - `provider` 'agentcard', required
          - `provider_config` union: Select a provider config by ID or name. Responses return the ID. Renaming a config does not change existing wallet bindings; an item cannot switch to a different config after creation.
            - object
              - …
            - object
              - …
          - `user_id` string
        - KernelWalletVaultItemSpec: Cards stored with Kernel-managed credentials, each a payment method of the wallet. Each card is enrolled through a card_enrollment action: the cardholder enters the card and their email on a Kernel-hosted page. Where the wallet advertises add_payment_method, creation returns an empty connected wallet and each card is enrolled with that operation. Otherwise creation returns the wallet's default card's card_enrollment action, and the wallet connects once that card is stored. Kernel then enrolls each card for an agentic network token when the issuer supports it. The card number never reaches Kernel. The connected wallet's payment_methods expansion lists the cards; capabilities.single_use_card.eligible is false, with a network_token_* reason, until the card has a network token, and authorize returns 400 for such a card unless Kernel supports checkout delivery without a network token for that card. In that case, fill types the checkout details. Visa purchases require the cardholder to complete a spend_approval action before Kernel issues a one-time code; Mastercard purchases need no hosted approval.
          - `provider` 'kernel', required
        - ShopPayWalletVaultItemSpec: Shop Pay wallet connected through Kernel's Shop app. Creation returns a shop_pay_oauth action: the shopper signs in to Shop and approves the connection, and the wallet connects. The connected wallet's payment_methods expansion lists the shopper's saved Shop Pay cards.
          - `authorization` ShopPayOAuthAuthorization, required
            - `client` KernelManagedOAuthClient, required
              - …
            - `method` 'oauth', required
          - `provider` 'shop_pay', required
      - `state` union, required
        - LinkWalletState
          - `provider` 'link', required
          - `status` 'pending_authorization' | 'connected' | 'declined' | 'reconnect_required' | 'degraded', required
          - `status_reason` string
        - AgentCardWalletState
          - `provider` 'agentcard', required
          - `status` 'pending_authorization' | 'connected' | 'degraded', required
          - `status_reason` string
          - `user_id` string: AgentCard user id linked to this wallet. Present once connected.
        - KernelWalletState
          - `provider` 'kernel', required
          - `status` 'pending_authorization' | 'connected' | 'reconnect_required' | 'degraded', required: connected means the wallet is usable. It holds zero or more cards as payment methods, listed by the payment_methods expansion, and each can pay once it reports capabilities.single_use_card.eligible. A wallet with no cards, before its first card or after its last is removed, is still connected. Where the wallet advertises add_payment_method and remove_payment_method, use them to manage cards. Otherwise the wallet enrolls one default card when created; until that card is enrolled the wallet reports pending_authorization with the card's card_enrollment action, or degraded when the card's enrollment outcome is unknown and the wallet must be deleted before adding another card. reconnect_required appears only on a wallet created before cards were payment methods and not yet upgraded. Reads preserve its stored state until the operator upgrade; payment and deletion requests are refused until then.
          - `status_reason` string
        - ShopPayWalletState
          - `provider` 'shop_pay', required
          - `status` 'pending_authorization' | 'connected' | 'declined' | 'reconnect_required' | 'degraded', required
          - `status_reason` string
      - `type` 'wallet', required
      - `updated_at` string, date-time, required
    - CardVaultItem
      - `action` union
        - LinkOAuthAction
          - `name` 'link_oauth', required
          - `url` string, uri, required
        - ShopPayOAuthAction
          - `name` 'shop_pay_oauth', required
          - `url` string, uri, required: Shop sign-in page where the shopper connects their Shop account to Kernel.
        - OnePasswordOAuthAction
          - `name` '1password_oauth', required
          - `url` string, uri, required: 1Password-hosted OAuth authorization URL for the human to open.
        - SpendApprovalAction
          - `name` 'spend_approval', required
          - `url` string, uri, required
        - PushApprovalAction
          - `name` 'push_approval', required
        - CollectAction
          - `name` 'collect', required
        - MfaAction
          - `name` 'mfa', required
        - EmbeddedCeremonyAction
          - `name` 'embedded_ceremony', required
        - CardEnrollmentAction
          - `capture_token` string: Secret bearer capability for embedded card capture with @onkernel/vault-react. Present only for Kernel wallets; never for AgentCard. Treat it like the enrollment URL and do not log or persist it in browser storage.
          - `name` 'card_enrollment', required
          - `url` string, uri, required
      - `available_expansions` AvailableVaultItemExpansion[], required
        - `description` string, required
        - `type` 'payment_methods' | 'link_user_info' | 'link_shipping_addresses', required
      - `available_operations` AvailableVaultItemOperation[], required
        - `description` string, required
        - `type` 'authorize' | 'restart_verification' | 'confirm_transaction' | 'collect' | 'prepare_checkout' | 'fill' | 'arm_passkey' | 'register_passkey' | 'disarm_passkey' | '1pw_create_access_request' | '1pw_access_request_status' | '1pw_fill' | '1pw_recover' | '1pw_update_access_token' | 'webmcp_invoke' | 'add_payment_method' | 'remove_payment_method', required
      - `created_at` string, date-time, required
      - `expires_at` string, date-time
      - `id` string, required
      - `key` string, required: Immutable item key assigned when the item is created.
      - `spec` union, required
        - LinkCardVaultItemSpec: Live Link card request. Test-mode card creation is not supported. The spec can be changed with PATCH until the card is authorized at a checkout. Authorize it with the browser at final checkout: Kernel inspects the checkout through WebMCP and internally chooses a merchant-bound Link Pay Token when supported or a virtual card otherwise. Callers never receive or choose how the credential is delivered.
          - `amount` integer, required: Integer amount in minor currency units, at most 50000. With recurring, the spending limit per period, not a lifetime total.
          - `context` string, required
          - `currency` string, required
          - `line_items` LinkLineItem[]
            - `description` string
            - `image_url` string
            - `name` string, required
            - `product_url` string
            - `quantity` integer
            - `sku` string
            - `totals` LinkTotal[]
              - …
            - `unit_amount` integer: Unit amount in minor currency units.
            - `url` string
          - `merchant_name` string, required
          - `merchant_url` string, uri, required
          - `metadata` object
          - `payment_method_id` string, required: Payment-method ID returned by the referenced wallet's payment-method listing. The provider decides whether the selected funding method can satisfy the card request.
          - `provider` 'link', required
          - `recurring` LinkRecurring: Recurring terms for a subscription or other repeated purchase. The amount becomes the spending limit for each period of interval_count intervals, for example every 2 weeks. The merchant schedules charges. The card stays ready after each charge until it expires or is deleted; do not create a new card each period. Deleting the card, its wallet or its vault first cancels the credential with Link, so later charges decline; if Link cannot be reached, deletion returns 409 provider_revocation_pending and should be retried. Deletion does not cancel the subscription with the merchant. Recurring terms cannot be changed once the card is authorized.
            - `interval` 'day' | 'week' | 'month' | 'year', required
            - `interval_count` integer: Number of intervals per period. Link defaults it to 1.
          - `totals` LinkTotal[]
            - `amount` integer, required: Total amount in minor currency units.
            - `display_text` string, required
            - `type` string, required
          - `wallet` string, required: Connected Link wallet item key.
        - AgentCardCardVaultItemSpec: AgentCard reusable live payment card. Test-mode card creation is not supported. Each checkout creates an authorization for spec.merchant / spec.amount that the cardholder approves, unless AgentCard runs it under one of the cardholder's autopilot rules. The card stays ready after each authorization.
          - `amount` integer, required: Integer amount in minor currency units.
          - `card_id` string: Opaque card ID returned by AgentCard for a card in the connected wallet. Pass it through unchanged without assuming a prefix or format. Omitted, the cardholder picks on the approval screen.
          - `checkout_origin` string: Origin of the top-level checkout page, such as https://shop.example.com: https, a lowercase host, a port only when it is not 443, and no path. http is accepted only for localhost test pages. Checkouts without a preparation send it to AgentCard, which uses it to match the cardholder's autopilot rules; prepared checkouts send the preparation's merchant_origin instead. Kernel sends the declared value and does not compare it with the page the browser has open. Omitted, those checkouts ask the cardholder to approve. Card updates replace the whole spec, so an update that omits it removes it.
          - `currency` string, required
          - `merchant` string, required: Merchant name shown on the cardholder's approval screen.
          - `provider` 'agentcard', required
          - `wallet` string, required: Wallet item key used to authorize checkouts.
        - KernelCardVaultItemSpec: One live purchase with a Kernel-enrolled card. Authorization obtains an agentic network token number, expiry and one-time 3-digit code. They are stored encrypted for the fill operation, which types them only on merchant_url's origin; the merchant's own checkout submits the payment. The one-time code is valid until the item's expires_at; fill and submit checkout before then. Mastercard purchases need no cardholder approval. A Visa purchase returns a spend_approval action: the cardholder approves it with a Visa passkey, and Kernel registers a Visa intent for one transaction up to the amount before issuing the code. For supported cards whose network cannot be enrolled for agentic tokens, authorize returns pending_authorization with a spend_approval action to collect a fresh security code in a hosted field. Once collected, the card is ready and can be filled before its expires_at, by default five minutes after collection. An expired card requires a new purchase. Fill types those details on merchant_url's origin. The amount, merchant_url and merchant_country are recorded but do not restrict payment requests sent by the browser. Card updates are not supported; delete and create a new item instead.
          - `amount` integer, required: Integer amount in minor currency units (at most 1000000), bound to the one-time code.
          - `currency` string, required: ISO 4217 code. Supported: aud, brl, cad, chf, czk, dkk, eur, gbp, hkd, inr, jpy, krw, mxn, nok, nzd, pln, sek, sgd, usd, zar.
          - `merchant_category` string: Actual merchant category when known. Omit rather than invent a category.
          - `merchant_category_code` string: Actual merchant MCC when known. Omit rather than invent a code. 0000 is not accepted.
          - `merchant_country` string: The merchant's ISO 3166-1 alpha-2 country code. Required for Visa cards, whose one-time code is issued for the merchant's country.
          - `merchant_name` string, required
          - `merchant_url` string, uri, required: Merchant checkout URL. Fill is allowed only on this URL's origin.
          - `payment_method_id` string: Wallet-scoped payment method ID from the wallet's payment_methods expansion. Omission selects the wallet's default card, ID card, for compatibility with existing requests; it never falls back to another method, and a wallet without a default card requires the ID. The purchase is bound to the method's enrolled card and network token, so later operations cannot switch funding.
          - `provider` 'kernel', required
          - `wallet` string, required: Key of the Kernel wallet item whose enrolled card pays.
        - ShopPayCardVaultItemSpec: Shop Pay purchase. amount is the limit the shopper approves; totals must include exactly one positive total no higher than it. context is shown to the shopper when they approve. Authorize it with the browser at final checkout: Kernel sends that page to Shop as the merchant and the card fills only on its origin. Without browser_id and page_url it authorizes for merchant_url. authorize returns an approval action for the shopper, who approves the purchase in Shop; share its URL unchanged when present. Report the merchant outcome with confirm_transaction, which ends the card.
          - `amount` integer, required: Approval limit in minor currency units, at most 1000000.
          - `context` string, required: What is being bought and why, written for the shopper.
          - `currency` string, required: Shop accepts USD spend requests only.
          - `line_items` ShopPayLineItem[]
            - `name` string, required
            - `quantity` integer, required
            - `unit_amount` integer, required: Unit price in minor currency units.
          - `merchant_country` string: ISO 3166-1 alpha-2 country of the merchant.
          - `merchant_name` string, required
          - `merchant_url` string, uri, required: The merchant's https URL.
          - `payment_method_id` string: Card ID from the wallet's payment_methods expansion. Omit it to use the shopper's preferred card.
          - `provider` 'shop_pay', required
          - `totals` ShopPayTotal[], required
            - `amount` integer, required: Amount in minor currency units; discounts are negative.
            - `type` string, required: For example subtotal, fulfillment, tax, discount or total.
          - `wallet` string, required: Connected Shop Pay wallet item key.
      - `state` union, required
        - LinkCardState: Issued Link cards retain encrypted card material for the fill operation. Link cards do not expose aliases or support egress substitution.
          - `domains` string[]
          - `masks` VaultItemMasks
            - `brand` string
            - `last4` string
            - `token_last4` string: Last four digits of the network token presented to the merchant.
          - `provider` 'link', required
          - `status` 'requested' | 'pending_authorization' | 'ready' | 'consumed' | 'expired' | 'declined' | 'recovery_required', required: recovery_required means an original provider operation has an unresolved outcome and the card cannot be used. Reads keep observing a known provider request and may clear the recovery. To continue, delete this card and create a new one; deleting cancels the original request when its ID is known and keeps the recovery evidence. The user may see an approval request for the original card and should approve only the new one.
          - `status_reason` string
        - AgentCardCardState
          - `aliases` VaultCardAliases
            - `cvc` string, required
            - `exp_month` string, required
            - `exp_year` string, required
            - `number` string, required
          - `authorization` AgentCardCheckoutAuthorization: The in-flight or most recent checkout authorization. Present while a checkout is pending approval and after it settles.
            - `actual_cents` integer
            - `amount` string: Display amount shown on the approval screen.
            - `amount_authority` 'display_only' | 'stripe_payment_intent'
            - `amount_cents` integer, required
            - `amount_verified` boolean
            - `approval_url` string, uri
            - `browser_id` string: Browser session that submitted the checkout.
            - `charged_amount_cents` integer
            - `charged_currency` string
            - `charged_kind` 'captured' | 'authorized' | 'none'
            - `created_at` string, date-time, required
            - `currency` string, required
            - `expected_cents` integer
            - `expires_at` string, date-time
            - `id` string, required
            - `merchant` string, required
            - `psp` string, required
            - `psp_error_code` string
            - `reason` string
            - `replay_attempted` boolean
            - `replay_delivered` boolean: Whether the processor response was delivered to the browser.
            - `replay_status` integer: HTTP status of the replayed processor response.
            - `status` 'awaiting_approval' | 'approved' | 'declined' | 'expired', required
          - `masks` VaultItemMasks
            - `brand` string
            - `last4` string
            - `token_last4` string: Last four digits of the network token presented to the merchant.
          - `preparation` AgentCardCheckoutPreparation: One-use processor-bound checkout preparation. Keep the approval page open through device handoff, including Adyen encryption. The amount is declared by the caller and does not constrain the merchant's eventual charge. Adyen device approval and browser Authorised responses are not capture or fulfillment evidence.
            - `approval_url` string, uri
            - `browser_id` string, required
            - `created_at` string, date-time, required
            - `environment` 'production' | 'sandbox' | 'shared', required
            - `expires_at` string, date-time: When ready, the absolute deadline to submit the first native request; no later than provider readiness expiry or 30 seconds after Kernel first observes readiness. Polling never extends this deadline.
            - `id` string
            - `merchant_origin` string, required
            - `psp` 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago' | 'adyen', required
            - `status` 'creating' | 'awaiting_approval' | 'ready' | 'consumed' | 'cancelled' | 'expired' | 'unknown', required: Preparation consumed means egress claimed the preparation and it cannot be reused. It does not mean the attempt settled. Use the enclosing item's status as the lifecycle indicator; item consumed means the attempt settled, not that an order or charge succeeded.
          - `provider` 'agentcard', required
          - `status` 'requested' | 'ready' | 'preparing' | 'ready_to_submit' | 'pending_approval' | 'consumed' | 'stopped' | 'outcome_unknown' | 'degraded' | 'recovery_required', required: ready_to_submit is device readiness for at most 30 seconds. consumed means the prepared attempt has settled, not that an order succeeded. stopped cannot be reused. outcome_unknown requires merchant reconciliation and blocks new requests. recovery_required means the original checkout outcome is unresolved. Automatic reuse is blocked. Known authorization IDs must be reconciled through provider observations or support. When no authorization ID was returned, an explicitly confirmed item deletion may abandon the unresolved attempt so the caller can create a replacement; deletion does not prove that the original attempt failed. It does not mean declined or expired.
          - `status_reason` string
        - KernelCardState: A ready Kernel card supports authorize, fill, then submit checkout. Card details are delivered for a few minutes after fill; submit promptly. Repeated fill is safe and never submits checkout. Visa purchases require a spend_approval action before details are issued; Mastercard purchases need no hosted approval. masks.last4 is the enrolled card's last four digits; masks.token_last4, when present, is the token's last four digits shown to the merchant. Kernel does not observe whether the merchant charged the card.
          - `domains` string[]: Informational registrable domain. Fill is locked to merchant_url's exact origin.
          - `funding_status` 'available' | 'unavailable' | 'removed': Whether payment_method_id can still fund this purchase. unavailable means the method is being removed or awaits recovery, so authorization, fill and confirmation are refused until it recovers. removed means the method was removed from its wallet, so this purchase can no longer be paid; create a new purchase with another method. Neither changes status, which still reports what already happened to this purchase.
          - `masks` VaultItemMasks
            - `brand` string
            - `last4` string
            - `token_last4` string: Last four digits of the network token presented to the merchant.
          - `payment_method_id` string: Wallet-scoped ID of the payment method funding this purchase. It is bound when the purchase is created and never changes; purchases created before payment methods could be selected report the wallet's default card, card.
          - `provider` 'kernel', required
          - `status` 'requested' | 'pending_authorization' | 'ready' | 'consumed' | 'expired' | 'declined' | 'recovery_required', required: pending_authorization waits for cardholder approval on Visa purchases or fresh security-code collection on alias-mode purchases through the spend_approval action; an unused link expires after 30 minutes. Alias-mode cards become ready after collection and expire at the temporary security-code alias deadline, by default five minutes later. An expired alias purchase requires a new card. recovery_required means verification, approving the purchase or issuing the one-time code has an unresolved outcome. A server-classified initial attestation failure before intent dispatch may advertise restart_verification to prepare a fresh local verification link; this does not approve spending or replay any provider request. Unclassified legacy recovery and uncertain intent creation cannot restart. Kernel never approves again or issues another code for the item automatically. To continue, delete this card and create a new purchase; the cardholder approves the new purchase separately. Recovery while reporting a merchant transaction cannot be deleted and must be reconciled with support. When status_reason says the provider refused retrieval before acceptance, no code was issued and a later read retries. declined means the card network refused to issue a code.
          - `status_reason` string
        - ShopPayCardState: Issued Shop Pay cards retain encrypted card material for the fill operation.
          - `domains` string[]
          - `masks` VaultItemMasks
            - `brand` string
            - `last4` string
            - `token_last4` string: Last four digits of the network token presented to the merchant.
          - `provider` 'shop_pay', required
          - `status` 'requested' | 'pending_authorization' | 'ready' | 'consumed' | 'expired' | 'declined' | 'recovery_required', required: declined covers a request the shopper declined or that was cancelled. consumed means the transaction outcome was reported with confirm_transaction; the card is no longer stored and cannot be filled again, whatever the outcome. recovery_required means a provider operation has an unresolved outcome and the card cannot be used. When status_reason says the provider refused retrieval before acceptance, no card was issued and a later read retries. Otherwise follow status_reason: recovery for issuance can be abandoned by deleting the card and creating a new one, and the shopper approves the new purchase separately. Recovery while reporting a merchant transaction cannot be deleted and must be reconciled with support.
          - `status_reason` string
      - `type` 'card', required
      - `updated_at` string, date-time, required
    - PaymentRequestVaultItem: One purchase from a Link or Kernel wallet, parented by that wallet. It has the same lifecycle, operations and fill behavior as a Link or Kernel card item. AgentCard reusable cards remain card items.
      - `action` union
        - LinkOAuthAction
          - `name` 'link_oauth', required
          - `url` string, uri, required
        - ShopPayOAuthAction
          - `name` 'shop_pay_oauth', required
          - `url` string, uri, required: Shop sign-in page where the shopper connects their Shop account to Kernel.
        - OnePasswordOAuthAction
          - `name` '1password_oauth', required
          - `url` string, uri, required: 1Password-hosted OAuth authorization URL for the human to open.
        - SpendApprovalAction
          - `name` 'spend_approval', required
          - `url` string, uri, required
        - PushApprovalAction
          - `name` 'push_approval', required
        - CollectAction
          - `name` 'collect', required
        - MfaAction
          - `name` 'mfa', required
        - EmbeddedCeremonyAction
          - `name` 'embedded_ceremony', required
        - CardEnrollmentAction
          - `capture_token` string: Secret bearer capability for embedded card capture with @onkernel/vault-react. Present only for Kernel wallets; never for AgentCard. Treat it like the enrollment URL and do not log or persist it in browser storage.
          - `name` 'card_enrollment', required
          - `url` string, uri, required
      - `available_expansions` AvailableVaultItemExpansion[], required
        - `description` string, required
        - `type` 'payment_methods' | 'link_user_info' | 'link_shipping_addresses', required
      - `available_operations` AvailableVaultItemOperation[], required
        - `description` string, required
        - `type` 'authorize' | 'restart_verification' | 'confirm_transaction' | 'collect' | 'prepare_checkout' | 'fill' | 'arm_passkey' | 'register_passkey' | 'disarm_passkey' | '1pw_create_access_request' | '1pw_access_request_status' | '1pw_fill' | '1pw_recover' | '1pw_update_access_token' | 'webmcp_invoke' | 'add_payment_method' | 'remove_payment_method', required
      - `created_at` string, date-time, required
      - `expires_at` string, date-time
      - `id` string, required
      - `key` string, required: Immutable item key assigned when the item is created.
      - `spec` union, required
        - LinkCardVaultItemSpec: Live Link card request. Test-mode card creation is not supported. The spec can be changed with PATCH until the card is authorized at a checkout. Authorize it with the browser at final checkout: Kernel inspects the checkout through WebMCP and internally chooses a merchant-bound Link Pay Token when supported or a virtual card otherwise. Callers never receive or choose how the credential is delivered.
          - `amount` integer, required: Integer amount in minor currency units, at most 50000. With recurring, the spending limit per period, not a lifetime total.
          - `context` string, required
          - `currency` string, required
          - `line_items` LinkLineItem[]
            - `description` string
            - `image_url` string
            - `name` string, required
            - `product_url` string
            - `quantity` integer
            - `sku` string
            - `totals` LinkTotal[]
              - …
            - `unit_amount` integer: Unit amount in minor currency units.
            - `url` string
          - `merchant_name` string, required
          - `merchant_url` string, uri, required
          - `metadata` object
          - `payment_method_id` string, required: Payment-method ID returned by the referenced wallet's payment-method listing. The provider decides whether the selected funding method can satisfy the card request.
          - `provider` 'link', required
          - `recurring` LinkRecurring: Recurring terms for a subscription or other repeated purchase. The amount becomes the spending limit for each period of interval_count intervals, for example every 2 weeks. The merchant schedules charges. The card stays ready after each charge until it expires or is deleted; do not create a new card each period. Deleting the card, its wallet or its vault first cancels the credential with Link, so later charges decline; if Link cannot be reached, deletion returns 409 provider_revocation_pending and should be retried. Deletion does not cancel the subscription with the merchant. Recurring terms cannot be changed once the card is authorized.
            - `interval` 'day' | 'week' | 'month' | 'year', required
            - `interval_count` integer: Number of intervals per period. Link defaults it to 1.
          - `totals` LinkTotal[]
            - `amount` integer, required: Total amount in minor currency units.
            - `display_text` string, required
            - `type` string, required
          - `wallet` string, required: Connected Link wallet item key.
        - KernelPaymentRequestVaultItemSpec: One live purchase funded by the Kernel wallet payment method named by payment_method_id. The method must be active and eligible when the request is created. The purchase is bound to that method; later operations cannot switch funding, and removing the method makes the purchase unusable rather than moving it to another card. Approval, issuance, fill and the alias fallback behave as described for KernelCardVaultItemSpec.
          - `amount` integer, required: Integer amount in minor currency units (at most 1000000), bound to the one-time code.
          - `currency` string, required: ISO 4217 code. Supported: aud, brl, cad, chf, czk, dkk, eur, gbp, hkd, inr, jpy, krw, mxn, nok, nzd, pln, sek, sgd, usd, zar.
          - `merchant_category` string: Actual merchant category when known. Omit rather than invent a category.
          - `merchant_category_code` string: Actual merchant MCC when known. Omit rather than invent a code. 0000 is not accepted.
          - `merchant_country` string: The merchant's ISO 3166-1 alpha-2 country code. Required for Visa cards, whose one-time code is issued for the merchant's country.
          - `merchant_name` string, required
          - `merchant_url` string, uri, required: Merchant checkout URL. Fill is allowed only on this URL's origin.
          - `payment_method_id` string, required: Payment method ID from the wallet's payment_methods expansion.
          - `provider` 'kernel', required
          - `wallet` string, required: Key of the Kernel wallet item that owns the payment method.
      - `state` union, required
        - LinkCardState: Issued Link cards retain encrypted card material for the fill operation. Link cards do not expose aliases or support egress substitution.
          - `domains` string[]
          - `masks` VaultItemMasks
            - `brand` string
            - `last4` string
            - `token_last4` string: Last four digits of the network token presented to the merchant.
          - `provider` 'link', required
          - `status` 'requested' | 'pending_authorization' | 'ready' | 'consumed' | 'expired' | 'declined' | 'recovery_required', required: recovery_required means an original provider operation has an unresolved outcome and the card cannot be used. Reads keep observing a known provider request and may clear the recovery. To continue, delete this card and create a new one; deleting cancels the original request when its ID is known and keeps the recovery evidence. The user may see an approval request for the original card and should approve only the new one.
          - `status_reason` string
        - KernelCardState: A ready Kernel card supports authorize, fill, then submit checkout. Card details are delivered for a few minutes after fill; submit promptly. Repeated fill is safe and never submits checkout. Visa purchases require a spend_approval action before details are issued; Mastercard purchases need no hosted approval. masks.last4 is the enrolled card's last four digits; masks.token_last4, when present, is the token's last four digits shown to the merchant. Kernel does not observe whether the merchant charged the card.
          - `domains` string[]: Informational registrable domain. Fill is locked to merchant_url's exact origin.
          - `funding_status` 'available' | 'unavailable' | 'removed': Whether payment_method_id can still fund this purchase. unavailable means the method is being removed or awaits recovery, so authorization, fill and confirmation are refused until it recovers. removed means the method was removed from its wallet, so this purchase can no longer be paid; create a new purchase with another method. Neither changes status, which still reports what already happened to this purchase.
          - `masks` VaultItemMasks
            - `brand` string
            - `last4` string
            - `token_last4` string: Last four digits of the network token presented to the merchant.
          - `payment_method_id` string: Wallet-scoped ID of the payment method funding this purchase. It is bound when the purchase is created and never changes; purchases created before payment methods could be selected report the wallet's default card, card.
          - `provider` 'kernel', required
          - `status` 'requested' | 'pending_authorization' | 'ready' | 'consumed' | 'expired' | 'declined' | 'recovery_required', required: pending_authorization waits for cardholder approval on Visa purchases or fresh security-code collection on alias-mode purchases through the spend_approval action; an unused link expires after 30 minutes. Alias-mode cards become ready after collection and expire at the temporary security-code alias deadline, by default five minutes later. An expired alias purchase requires a new card. recovery_required means verification, approving the purchase or issuing the one-time code has an unresolved outcome. A server-classified initial attestation failure before intent dispatch may advertise restart_verification to prepare a fresh local verification link; this does not approve spending or replay any provider request. Unclassified legacy recovery and uncertain intent creation cannot restart. Kernel never approves again or issues another code for the item automatically. To continue, delete this card and create a new purchase; the cardholder approves the new purchase separately. Recovery while reporting a merchant transaction cannot be deleted and must be reconciled with support. When status_reason says the provider refused retrieval before acceptance, no code was issued and a later read retries. declined means the card network refused to issue a code.
          - `status_reason` string
      - `type` 'payment_request', required
      - `updated_at` string, date-time, required
    - CredentialAccountVaultItem
      - `action` OnePasswordOAuthAction
        - `name` '1password_oauth', required
        - `url` string, uri, required: 1Password-hosted OAuth authorization URL for the human to open.
      - `available_expansions` AvailableVaultItemExpansion[], required
        - `description` string, required
        - `type` 'payment_methods' | 'link_user_info' | 'link_shipping_addresses', required
      - `available_operations` AvailableVaultItemOperation[], required: Advertises 1pw_recover when Kernel can recover a failed account link. Recovery is unavailable while authorization is pending or after the connection has already been reset.
        - `description` string, required
        - `type` 'authorize' | 'restart_verification' | 'confirm_transaction' | 'collect' | 'prepare_checkout' | 'fill' | 'arm_passkey' | 'register_passkey' | 'disarm_passkey' | '1pw_create_access_request' | '1pw_access_request_status' | '1pw_fill' | '1pw_recover' | '1pw_update_access_token' | 'webmcp_invoke' | 'add_payment_method' | 'remove_payment_method', required
      - `created_at` string, date-time, required
      - `expires_at` string, date-time
      - `id` string, required
      - `key` string, required: Immutable item key assigned when the item is created.
      - `spec` OnePasswordCredentialAccountSpec, required
        - `authorization` OnePasswordOAuthAuthorization, required
          - `client` KernelManagedOAuthClient, required
            - `type` 'kernel_managed', required
          - `method` 'oauth', required
        - `provider` '1password', required
      - `state` OnePasswordCredentialAccountState, required
        - `provider` '1password', required
        - `status` 'pending_authorization' | 'connected' | 'reconnect_required' | 'declined', required
        - `status_reason` string
      - `type` 'credential_account', required
      - `updated_at` string, date-time, required
    - CredentialVaultItem
      - `action` union
        - CredentialCollectionAction: One schema-derived form for the item, available in ready or pending_collection state. Render every form-supported field as editable; omit totp and passkey fields and preserve their stored values. Prefill non-sensitive values, and allow existing sensitive values to be preserved or replaced without ever revealing them. No field subsets or per-request form configuration exist. Validate required fields against the resulting values, including preserved secrets. Submit changed values only, using the version used to render the form. Scoped hosted submission rejects totp and passkey edits; those writes require the ordinary authenticated item API. Customer forms likewise omit them from their payloads. Save edits atomically. A successful hosted submission increments the version, marks ready, and consumes the session; an empty edit may complete collection while preserving values. A customer form uses PATCH for changed values and does not send an empty PATCH when nothing changed. Kernel-hosted bearer sessions require no Kernel account and are bound to the item version. Expired, superseded, consumed, or deleted-item sessions cannot submit. Authenticated item GET renews expired active sessions for ready or pending items; pending items always receive an action. A ready item with no active session omits the action until collect is invoked. Concurrent renewals return the same link. Renewal changes neither values nor item version. An expired link cannot renew itself. The hosted form handles its collection protocol; callers only open the returned URL and do not extract or submit its token through the public API. For customer-hosted forms, use @onkernel/vault-react and an authenticated customer backend calling the ordinary item GET/PATCH API. Kernel does not store customer collection URLs or authenticate the customer's end users. Treat URLs and submitted values as secrets and exclude them from logs, traces, and errors.
          - `expires_at` string, date-time, required: Expiry of the Kernel-hosted collection link (30 minutes after issuance).
          - `name` 'collect', required
          - `url` string, uri, required: Time-scoped hosted form URL (vault.kernel.sh in production). Open this URL as returned; treat it as a secret.
        - OnePasswordAccessApprovalAction
          - `instructions` string, required: Steps for the agent to hand approval to the human and poll the resulting decision.
          - `name` '1password_access_approval', required
          - `url` string, uri, required: Native 1Password approval link. Present it to the account owner without modifying it; it does not grant access until they approve in their app.
      - `available_expansions` AvailableVaultItemExpansion[], required
        - `description` string, required
        - `type` 'payment_methods' | 'link_user_info' | 'link_shipping_addresses', required
      - `available_operations` AvailableVaultItemOperation[], required: Kernel credentials advertise collect and fill when eligible. 1Password credentials advertise 1pw_create_access_request until a request is made, 1pw_access_request_status while its approval is pending, and 1pw_fill after access is granted. Managed auth credentials advertise fill while ready and nothing otherwise.
        - `description` string, required
        - `type` 'authorize' | 'restart_verification' | 'confirm_transaction' | 'collect' | 'prepare_checkout' | 'fill' | 'arm_passkey' | 'register_passkey' | 'disarm_passkey' | '1pw_create_access_request' | '1pw_access_request_status' | '1pw_fill' | '1pw_recover' | '1pw_update_access_token' | 'webmcp_invoke' | 'add_payment_method' | 'remove_payment_method', required
      - `created_at` string, date-time, required
      - `id` string, required
      - `key` string, required: Immutable item key assigned when the item is created.
      - `spec` union, required
        - KernelCredentialVaultItemSpec
          - `description` string: Recognizable site or service name displayed verbatim as the form title, without suffixes such as sign-in credentials. Display text only, not an enforced destination policy.
          - `fields` CredentialVaultFieldDefinition[], required: Ordered field definitions rendered in this order by credential collection forms.
            - `label` string: Optional human-readable display label. It is returned as non-secret metadata and never affects value keys, updates, or browser fills. Use single-line, trimmed display text without control or formatting characters. The server enforces a 128-byte UTF-8 limit.
            - `name` string, required: Stable field name used to key values, updates, and browser fills.
            - `required` boolean, required: Whether a nonempty value is required for readiness and form submission.
            - `sensitive` boolean, required: Whether the value is omitted from every item response. Reserve true for secrets such as passwords, API tokens, and TOTP seeds. Ordinary usernames and email addresses should be false so the form can display and prefill them.
            - `type` 'text' | 'email' | 'password' | 'totp' | 'passkey', required: Text, email, and password have form inputs; totp and passkey do not and are omitted from both Kernel-hosted and customer React forms. Password, totp, and passkey must be sensitive. A totp value is an RFC 4648 Base32 generator seed (case-insensitive, optional trailing padding), not an otpauth URI or current code. Reject invalid or empty decoded seeds. Browser fill generates an RFC 6238 code at execution time using HMAC-SHA1, 6 digits, and a 30-second period. Preserve leading zeros; never fill the seed. Custom algorithms, digits, periods, and form enrollment are unsupported. A passkey value is a JSON-encoded FIDO Credential Exchange Format passkey object with unpadded base64url `credentialId`, `userHandle` (at most 64 bytes), and `key` (a PKCS#8 ECDSA P-256 private key), a lowercase `rpId` domain, and optional `username` and `userDisplayName`. Other CXF members are ignored. Passkeys are never filled into pages; use arm_passkey to sign in with one and register_passkey to create one.
          - `provider` 'kernel', required
        - OnePasswordCredentialVaultItemSpec: Stored-token credentials omit account and never return access_token or integration_key.
          - `access_token_expires_at` string, date-time: Customer-supplied expiry metadata, if provided.
          - `account` string
          - `provider` '1password', required
          - `requests` OnePasswordCredentialRequests, required: Credential Request v2 input sent to the extension. A credential item may request up to five login entries.
            - `entries` OnePasswordCredentialRequestEntry[], required
              - …
            - `goal` string
            - `version` integer, required: Must be 2.
        - ManagedAuthCredentialVaultItemSpec
          - `connection_id` string, required: ID of the managed auth connection whose saved credential this item reads. List connections with `GET /auth/connections`.
          - `description` string: Display text supplied when the item was created. Omitted when none was given.
          - `provider` 'managed_auth', required
      - `state` union, required
        - KernelCredentialVaultItemState
          - `fields` object, required: Exactly one entry for each declared field.
          - `provider` 'kernel', required
          - `status` 'pending_collection' | 'ready', required: Ready means all required fields have values, not that a login succeeded. Optional fields may remain unset.
        - OnePasswordCredentialVaultItemState
          - `access_request` OnePasswordAccessRequestState: Non-secret broker state. Granted credential references are returned in resolved only for credentials with a customer-supplied access token; otherwise they stay encrypted server-side and can only be used by the fill operation.
            - `createdAt` string: Provider-created timestamp as returned by the broker.
            - `entries` OnePasswordReturnedRequestEntry[]: Login entries returned directly on accessRequest by the observed extension build. Omitted when the provider does not supply them.
              - …
            - `goal` string: Goal echoed by the observed createAccessRequest response when present.
            - `granted_count` integer
            - `has_autofill_token` boolean, required
            - `id` string, required
            - `identity` string: Opaque provider identity returned by the broker.
            - `path` string: Provider path if supplied in the broker response.
            - `request` OnePasswordReturnedRequest: The request object if returned by the extension. The observed create response may omit entries; no entry IDs are invented.
              - …
            - `resolved` OnePasswordResolvedAccessRequestEntry[]: Granted logins in the shape 1Password's getAccessRequestStatus returns. Present only for ready credentials with a customer-supplied access token, on single-item responses to callers that can use the vault. Each reference works only with that credential's access token and integration key.
              - …
            - `state` string, required: One of pending, resolved, denied, or failed.
          - `access_request_id` string: Opaque request ID returned by the 1Password broker after a successful createAccessRequest call.
          - `provider` '1password', required
          - `status` 'pending_authorization' | 'ready' | 'declined' | 'failed', required
          - `status_reason` string
        - ManagedAuthCredentialVaultItemState
          - `fields` object: One entry per non-empty value on the connection's saved credential, keyed by the field name to use in fill bindings. Included on single-item responses (create and get) and omitted from list responses, like `value_keys` on credentials. Empty when unavailable or when every stored value is empty. A stored value named totp_secret is never listed or filled. Values are never returned. A totp entry is present when the credential has a TOTP seed; fill writes a generated code for it. Entries follow the connection's credential.
          - `provider` 'managed_auth', required
          - `status` 'ready' | 'unavailable', required: Items are created ready, which means the connection has a saved Kernel credential that stores values or a TOTP seed (what has_values or has_totp_secret report on credentials), not that a login succeeded. Unavailable means it no longer does; such items advertise no operations.
          - `status_reason` 'connection_not_found' | 'no_credential' | 'external_credential': Present when status is unavailable. connection_not_found means the connection was deleted. no_credential means the connection's credential was deleted or emptied after the item was created. external_credential means the connection was moved to an external credential provider.
      - `type` 'credential', required
      - `updated_at` string, date-time, required
      - `version` integer, required: Starts at 1 and increments on PATCH and successful hosted submission, but not collection-link renewal. Managed auth credentials stay at 1; changes to the underlying credential are read at fill time and do not change the version.
  - FillVaultItemOperationResult
    - `fields` VaultFillFieldResult[], required: One result per request binding, in request order; empty when the fill used no bindings. After the first failed or unknown field, all remaining fields are not_attempted.
      - `error_code` 'target_changed' | 'element_not_found' | 'ambiguous_selector' | 'element_not_editable' | 'option_not_found' | 'timeout' | 'execution_failed': Present only for failed or unknown fields. Never includes secret values, DOM content, or raw browser errors.
      - `index` integer, required: Zero-based index into the request fields array.
      - `status` 'filled' | 'failed' | 'not_attempted' | 'unknown', required: Filled means the fill action completed, not that the website retained or accepted the value.
    - `status` 'completed' | 'failed' | 'unknown', required: Completed when the fill finished. Failed when execution stopped with known outcomes. Unknown when an outcome cannot be determined. Completed means values were supplied to the page, not that the site accepted or submitted them.
    - `type` 'fill', required
  - PasskeyVaultItemOperationResult
    - `rp_id` string: Relying party the armed passkey answers for. Returned by arm_passkey.
    - `status` 'armed' | 'disarmed', required: armed means the browser will answer matching passkey requests; it does not mean a page has asked yet. disarmed means the browser no longer uses this item's passkeys.
    - `type` 'arm_passkey' | 'register_passkey' | 'disarm_passkey', required
  - OnePasswordFillVaultItemOperationResult: The submission result reported by the 1Password extension when available. Kernel returns fill_unknown if the extension call has no conclusive result. Inspect the page to determine successful authentication on the website.
    - `error_code` 'fillFailed' | 'autosubmitFailed' | 'noExistingCredentials' | 'authenticationFailed': Present for fill_failed, and for fill_unknown when the extension reported autosubmitFailed (it filled and submitted the form but could not confirm the fill finished). These are allowlisted 1Password extension codes, never raw errors, secrets, or page content.
    - `status` 'fill_submitted' | 'fill_failed' | 'fill_unknown', required: Kernel's outcome of the extension call. fill_submitted means the extension reported submission, not website authentication. fill_failed means the extension returned a known failure and includes error_code. fill_unknown means the form may have been filled or submitted without a conclusive result; inspect the page to see the result of the fill.
    - `type` '1pw_fill', required
  - WebMCPInvokeVaultItemOperationResult: Returns the same tool result fields as the browser WebMCP invoke API, plus the vault operation discriminator. Output and error text are untrusted page-provided data, returned without redaction; tools may include supplied vault values. Inspect the browser page to determine whether the intended site action succeeded.
    - `error_text` string: Untrusted page-provided error text, returned without redaction. May contain supplied vault values.
    - `invocation_id` string: Present when the browser reported one.
    - `output` unknown
    - `status` 'completed' | 'canceled' | 'error' | 'awaiting_submission' | 'unknown', required: Unknown means invocation may have run; do not retry automatically. No status confirms that the website accepted the action.
    - `type` 'webmcp_invoke', required
  - AddPaymentMethodVaultItemOperationResult: The payment method created in pending_enrollment. Deliver action.url to the cardholder; it is a single-use capability and must not be logged. Observe completion through the wallet's payment_methods expansion.
    - `payment_method` VaultPaymentMethod, required
      - `action` CardEnrollmentAction
        - `capture_token` string: Secret bearer capability for embedded card capture with @onkernel/vault-react. Present only for Kernel wallets; never for AgentCard. Treat it like the enrollment URL and do not log or persist it in browser storage.
        - `name` 'card_enrollment', required
        - `url` string, uri, required
      - `capabilities` VaultPaymentMethodCapabilities, required: Provider-reported advisory capabilities. A missing capability is unknown, not ineligible; only eligible=false is an explicit negative signal.
        - `single_use_card` VaultPaymentMethodCapability
          - `eligible` boolean, required
          - `reasons` string[], required
      - `display` VaultPaymentMethodDisplay, required
        - `brand` string
        - `label` string
        - `last4` string
      - `expires_at` string, date-time: Expiry of a pending enrollment link.
      - `id` string, required
      - `is_default` boolean, required: For Kernel wallets, true for the default card, ID card, which a Kernel card item that omits payment_method_id selects. Wallets created with payment methods enabled have no default card.
      - `provider` string, required: Provider that issued this payment-method ID.
      - `status` 'pending_enrollment' | 'active' | 'removal_pending' | 'recovery_required': Kernel wallets only. pending_enrollment means a card_enrollment link is open; active means the card is stored and can pay when capabilities.single_use_card.eligible is true; removal_pending means removal started but the provider outcome is unknown, so retry remove_payment_method; recovery_required means either an enrollment outcome is unknown (remove the method), or the stored card cannot be read (contact support; removal is refused with 409). Consult status_reason to distinguish these cases. Absent for other providers.
      - `status_reason` string
      - `type` string, required: Provider-neutral payment-method type normalized to lowercase.
    - `type` 'add_payment_method', required
  - RemovePaymentMethodVaultItemOperationResult
    - `payment_method_id` string, required
    - `status` 'removed', required
    - `type` 'remove_payment_method', required

## Other responses

- `400`: Bad Request – invalid input
- `401`: Unauthorized – missing or invalid authorization token
- `403`: Forbidden – insufficient permissions or plan
- `404`: Resource not found
- `409`: Conflict – resource already exists
- `429`: Too Many Requests – rate limit exceeded
- `500`: Internal Server Error
- `503`: Service unavailable

## Changes

- **2026-10-28** `324a13ba3570`: 7 breaking, 10 info
  - added `#/components/schemas/ShopPayCardState` to the `oneOf[#/components/schemas/VaultItem]/oneOf[#/components/schemas/CardVaultItem]/state` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/ShopPayCardVaultItemSpec` to the `oneOf[#/components/schemas/VaultItem]/oneOf[#/components/schemas/CardVaultItem]/spec` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/ShopPayOAuthAction` to the `oneOf[#/components/schemas/VaultItem]/oneOf[#/components/schemas/CardVaultItem]/action` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/ShopPayOAuthAction` to the `oneOf[#/components/schemas/VaultItem]/oneOf[#/components/schemas/PaymentRequestVaultItem]/action` response property `oneOf` list for the response status `200`
  - …13 more
- **2026-10-28** `70e83a0e6df4`: 1 info
  - added the optional property `oneOf[#/components/schemas/VaultItem]/oneOf[#/components/schemas/CredentialVaultItem]/spec/oneOf[#/components/schemas/OnePasswordCredentialVaultItemSpec]/requests/entries/items/id` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/onkernel/apis/kernel-api/changes/vaults/:id_or_name/items/:key/operations/post.md)

---

[API](https://skmtc.dev/onkernel/apis/kernel-api.md) - [All operations](https://skmtc.dev/onkernel/apis/kernel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/onkernel/apis/kernel-api/revisions/0f6cf4f58fe6?raw)