---
title: "Update a card specification or credential values"
method: PATCH
path: "/vaults/{id_or_name}/items/{key}"
tags: ["Vaults"]
---

# Update a card specification or credential values

`PATCH /vaults/{id_or_name}/items/{key}`

## Request

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

Credential updates require type credential and the current version, and change only values or description; omitted values are preserved, nonempty strings replace, and null or empty strings clear supported fields. Clearing required text/email/password values returns pending_collection; browser forms still require nonempty required inputs. Card updates may omit type for compatibility with legacy requests. Requested cards accept a replacement specification. Pending issuance requests may update provider-supported fields on their existing request, subject to atomic provider approval checks; omitted optional fields remain unchanged and explicit empty lists clear them. Wallet/provider binding and unsupported fields cannot change after authorization starts. An uncertain update enters recovery_required; delete the card and create a new one rather than retrying the update. Checkout cards may be edited between authorizations. A Link card authorized with browser_id and page_url cannot be changed; delete it and create a new card with the updated details.

## Request body

- union: Type must match the stored item; an update cannot change item type. Legacy card updates may omit type; payment_request updates require it. Credential updates require explicit type and version. Wallet updates are unsupported.
  - CardVaultItemUpdateRequest
    - `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[]
            - `amount` integer, required: Total amount in minor currency units.
            - `display_text` string, required
            - `type` string, required
          - `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.
    - `type` 'card'
  - PaymentRequestVaultItemUpdateRequest
    - `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[]
            - `amount` integer, required: Total amount in minor currency units.
            - `display_text` string, required
            - `type` string, required
          - `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.
    - `type` 'payment_request', required
  - CredentialVaultItemUpdateRequest: Atomically update description, field definitions, and selected values. Omitted properties are preserved. `remove_fields` deletes definitions and their values, then `add_fields` appends definitions, then `fields` sets values, including for added fields. An existing field's definition cannot be edited in place; to change it, remove the field and add it again, in the same update or a later one. The old value is deleted with it. Unknown field names return 400; stale versions or mismatched item types return 409 without changing the item. A successful update increments version and invalidates outstanding Kernel-hosted collection sessions. If required values remain missing, return pending_collection and a fresh collection action. Otherwise return ready without an action; collect can open the form again without clearing values. Customer URLs have no Kernel-managed expiry. 1Password and managed auth credentials return 409.
    - `expected_item_id` string: Optional immutable item ID precondition. Returns 409 if the key now identifies a different item. Accepted writes target this immutable ID, preventing replacement-key races. Supply this when submitting a form bound to a previously read item.
    - `spec` CredentialVaultItemSpecUpdate, required
      - `add_fields` CredentialVaultFieldDefinitionInput[]: Field definitions to append, with the same defaults as creation. Set their values in `fields` in the same update. Names must be unique after removals; at most 32 fields may result. A required totp or passkey field needs a value in `fields`.
        - `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: Unique stable field name used to key values, updates, and browser fills.
        - `required` boolean
        - `sensitive` boolean: Set false explicitly for ordinary usernames, email addresses, and other non-secret identifiers. Reserve true for secrets such as passwords, API tokens, and TOTP seeds. Password, totp, and passkey fields must be true. Omission defaults to true for safety; do not rely on that default for every field. False permits API reads and form prefilling.
        - `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.
      - `description` string: Recognizable site or service name used as the form title, without suffixes such as sign-in credentials. An empty string clears it. Display text only, not an enforced destination policy. The server also enforces a 16 KiB UTF-8 byte limit.
      - `fields` object
      - `remove_fields` string[]: Names of fields to delete with their values. Unknown names return 400. At least one field must remain.
    - `type` 'credential', required
    - `version` integer, required: Expected current item version from the latest read.

## Response `200`

Vault item updated

- 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
            - `limit` integer, nullable, required: Null means unlimited.
            - `remaining` integer, nullable, required: Amount still available in the rolling period; null means unlimited.
            - `used` integer, required: Amount already spent in the rolling period.
          - `per_transaction` LinkSpendLimit, required
            - `limit` integer, nullable, required: Null means unlimited.
          - `thirty_day` LinkRollingSpendLimit, required
            - `limit` integer, nullable, required: Null means unlimited.
            - `remaining` integer, nullable, required: Amount still available in the rolling period; null means unlimited.
            - `used` integer, required: Amount already spent in the rolling period.
        - `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
            - `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.
    - `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
            - KernelManagedOAuthClient
              - …
            - CustomerManagedOAuthClient
              - …
          - `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
            - `id` string, required
            - `name` string
          - object
            - `id` string
            - `name` string, required
        - `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
            - `type` 'kernel_managed', 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[]
            - `amount` integer, required: Total amount in minor currency units.
            - `display_text` string, required
            - `type` string, required
          - `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[]
            - `amount` integer, required: Total amount in minor currency units.
            - `display_text` string, required
            - `type` string, required
          - `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
            - `id` string: 1Password's ID for this entry in an access request you created. Supply it only with resolved.
            - `keywords` string[]
            - `parameters` object, required
              - …
            - `reason` string
            - `type` string, required: Must be login.
          - `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.
            - `id` string
            - `keywords` string[]
            - `parameters` object
              - …
            - `reason` string
            - `type` string
          - `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.
            - `entries` OnePasswordReturnedRequestEntry[]
              - …
            - `goal` string
            - `version` integer
          - `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.
            - `entryId` string: The requested entry this login satisfies, when known.
            - `reference` string, required: 1Password credential reference. Pass it unchanged as resourcePath to the extension's fillCredential or to the 1Password SDK.
          - `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.

## Other responses

- `400`: Bad Request – invalid input
- `401`: Unauthorized – missing or invalid authorization token
- `404`: Resource not found
- `409`: Conflict – resource already exists
- `500`: Internal Server Error

## Changes

- **2026-10-28** `324a13ba3570`: 2 warning, 1 info
  - the `oneOf[#/components/schemas/CardVaultItemUpdateRequest]/spec/oneOf[#/components/schemas/ShopPayCardVaultItemSpec]/amount` request property's max was set to `1000000.00`
  - changed the pattern of the request property `oneOf[#/components/schemas/CardVaultItemUpdateRequest]/spec/oneOf[#/components/schemas/ShopPayCardVaultItemSpec]/currency` from `^[A-Za-z]{3}$` to `^[Uu][Ss][Dd]$`
  - the `oneOf[#/components/schemas/CardVaultItem]/spec/oneOf[#/components/schemas/ShopPayCardVaultItemSpec]/currency` response's property pattern was changed from `^[A-Za-z]{3}$` to `^[Uu][Ss][Dd]$` for the status `200`
- **2026-10-28** `8e5483977604`: 7 breaking, 9 info
  - added `#/components/schemas/ShopPayCardState` to the `oneOf[#/components/schemas/CardVaultItem]/state` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/ShopPayCardVaultItemSpec` to the `oneOf[#/components/schemas/CardVaultItem]/spec` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/ShopPayOAuthAction` to the `oneOf[#/components/schemas/CardVaultItem]/action` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/ShopPayOAuthAction` to the `oneOf[#/components/schemas/PaymentRequestVaultItem]/action` response property `oneOf` list for the response status `200`
  - …12 more
- …earlier changes not shown

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

---

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