--- title: "Create or retrieve an identical vault item by immutable key" method: PUT path: "/vaults/{id_or_name}/items/{key}" tags: ["Vaults"] --- # Create or retrieve an identical vault item by immutable key `PUT /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 Create an item under a key unique within its vault, or retrieve the existing item when its specification matches. An identical card PUT returns the existing card in any lifecycle state without polling the provider, reauthorizing, replacing aliases, or resetting recovery. Conflicting specifications return 409. Provider-specific authorization requirements and retry behavior are described in the item's request schema. Do not use credential items to store, collect, or fill credit card data, including card numbers (PANs), security codes (CVV/CVC), or expiration dates. Use wallet, payment_request and card item types for credit cards and payment checkout instead. Where enabled, Link and Kernel purchases can be payment_request items parented by their wallet; card items remain supported for them and for AgentCard reusable cards. ## Request body - union - WalletVaultItemRequest - `spec` union, required - LinkWalletVaultItemRequestSpec - `authorization` union, required - KernelManagedLinkAuthorizationInput: Kernel starts and completes the user's Link authorization flow. - `client` KernelManagedOAuthClient, required - … - `method` 'oauth', required - ImportedLinkAuthorizationInput: The customer's backend completes Link OAuth and supplies the resulting tokens. For a new wallet, Kernel verifies the access token can access Link payment methods without consuming or rotating the refresh token. Valid access creates a wallet with state.status=connected. An expired, invalid, revoked, or insufficiently scoped access token returns 400 and no wallet is created. Refresh expired tokens in your backend before importing them. A failed import does not modify existing wallets. After successful import, Kernel owns subsequent refresh-token rotation; the customer must stop refreshing this grant. Import does not verify the refresh token: if it or the configured client credentials are rejected during a later refresh, the imported wallet becomes degraded. An unknown refresh outcome also leaves it degraded; Kernel does not retry a refresh token that may already have been consumed. There is no in-place reauthorization operation for an imported wallet. If this imported wallet's credentials become unusable, obtain a fresh Link OAuth grant in your backend and create a wallet under a NEW wallet key. Use the new wallet for NEW cards and payments, not to retry an old payment whose outcome is uncertain. This does not replace the old grant, rebind existing cards, or resolve their payment outcomes. Retain the old wallet and its cards while reconciling any uncertain payments with the provider or support. Do not repeat an uncertain payment on the new wallet, and do not treat deletion as evidence that it did not execute. Deletion of the old wallet can remain blocked by unresolved child cards. Repeating a create for the same item key and non-secret spec returns the existing wallet without replacing tokens, even if they have rotated or the wallet needs reconnection. ID and name references resolving to the same config are equivalent. A different config or non-secret spec returns 409. This create operation does not replace an existing grant. - `client` CustomerManagedOAuthClient, required - … - `method` 'oauth', required - `tokens` LinkWalletTokenInput, required: Send the token pair from your backend. Both tokens must be from the same Link grant under the referenced client. Supply a currently valid access token. Kernel refreshes when needed after import and uses the expiry returned by Link for subsequent tokens. Tokens are never returned in wallet responses, events, or logs. - … - `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 - `type` 'wallet', required - CardVaultItemRequest: Card items are supported for Link and Kernel purchases and are required for AgentCard reusable cards. Where enabled, Link and Kernel purchases can also be created as payment_request items. - `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', required - PaymentRequestVaultItemRequest: Create one Link or Kernel purchase under its wallet, where payment requests are enabled for the organization. Kernel requests must select payment_method_id explicitly. - `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 - CredentialAccountVaultItemRequest - `spec` OnePasswordCredentialAccountSpec, required - `authorization` OnePasswordOAuthAuthorization, required - `client` KernelManagedOAuthClient, required - `type` 'kernel_managed', required - `method` 'oauth', required - `provider` '1password', required - `type` 'credential_account', required - CredentialVaultItemRequest: Ask the end-user whether to link their site credential through 1Password. If they choose 1Password, connect their account and request access to a login in their own non-shared vault; passkeys are not supported. If they decline or that path fails, collect a Kernel-hosted credential item instead. Never automatically retry an uncertain 1Password request. After an uncertain fill, inspect the page to see the result of the fill. Do not use credential items for credit card data. Use wallet, payment_request and card item types instead. Kernel credentials declare fields and may enter pending_collection. 1Password credentials either reference a connected credential_account or store a supplied access token and integration key encrypted on the item. They store no login values or selectors. Managed auth credentials reference a managed auth connection in the same project that already has a saved credential, and read it at fill time; they store no values. Repeating the original creation request returns the current item without overwriting later state. A different request at the same key returns 409. - `spec` union, required - KernelCredentialVaultItemSpecInput: Credential fields are for login and other non-payment credentials. Do not store, collect, or fill credit card data in credential items. Use wallet, payment_request and card item types for credit cards and payment checkout instead. Field order is preserved in the user-facing collection form, so list fields in the same top-to-bottom order as the website. - `description` string: The site's recognizable display name, used verbatim as the user-facing form title (for example, Hacker News). Use only the site or service name; do not append sign-in, login, credentials, or task instructions. This is display text, not an enforced destination policy. At most 16 KiB in UTF-8 bytes. - `fields` CredentialVaultFieldInput[], required: Ordered field definitions. Use the website's top-to-bottom field order; the collection form renders this order unchanged. - `encrypted_value` string: Alternative to value for custom credential collection web apps. Use this only if you run your own credential collection web app and want values encrypted in the browser, sent to your backend still encrypted, and forwarded to Kernel's API still encrypted. In every other case, including server-side code that already holds the plaintext, use value. The field's value encrypted client-side as a compact JWE with alg ECDH-ES and enc A256GCM to the key from GET /vaults/{id_or_name}/encryption_key, with that key's kid in the protected header. Compression is not supported. The decrypted value follows the same rules as value, including that an empty string clears the field on update. A kid that is not this vault's key returns 400 encryption_key_mismatch; fetch the key again and re-encrypt. Other malformed or undecryptable values return 400 invalid_request. The whole request body is limited to 128 KiB. - `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. - `value` string: Optional initial value satisfying the declared type, at most 16 KiB in UTF-8 bytes. Omit to leave unset; null and empty strings are rejected on creation. Sensitive values are encrypted and never copied into the returned spec. Use this unless your own credential collection web app encrypts values in the browser; mutually exclusive with encrypted_value. - `provider` 'kernel', required - OnePasswordCredentialVaultItemSpecInput: A login request backed by a connected 1Password account or by a customer-supplied access token and matching integration key. Supply either account or both secrets, never both. Supplied secrets are write-only and never returned. Supply requests for new items; website remains supported for existing account-backed callers. To use an access request you already created and the user approved with the same access token and integration key, also supply access_request_id, resolved, and each requests entry's id; the item is created ready and Kernel doesn't create an access request. - `access_request_id` string: ID of an approved access request you created with this access_token and integration_key. Requires resolved. - `access_token` string: Customer-supplied 1Password broker token. Requires integration_key; stored encrypted on this item. Omit if providing a connected credential_account item via the account field. - `access_token_expires_at` string, date-time: Optional supplied token expiry metadata for stored-token credentials. Omit if providing a connected credential_account item via the account field. - `account` string: Key of a connected credential_account item in the same vault. Omit for stored-token credentials. - `integration_key` string: Matching customer-supplied integration key. Requires access_token; stored encrypted on this item. Omit if providing a connected credential_account item via the account field. - `provider` '1password', required - `requests` OnePasswordCredentialRequests: 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. - `resolved` OnePasswordResolvedAccessRequestEntry[]: Granted logins from 1Password's status for access_request_id, as returned by the 1Password SDK or extension. Requires access_request_id and an id on every requests entry. entryId may be omitted only when requests has one entry. Kernel doesn't verify the references; 1Password checks them when filling. - `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. - `website` string, uri: Legacy single-login shorthand. Supply requests instead. - ManagedAuthCredentialVaultItemSpecInput: A credential backed by a managed auth connection. The item stores no values: it reads the connection's saved credential at fill time, so updates made through managed auth apply immediately. The connection must be in the vault's project and hold a saved Kernel credential. The check is the saved credential, not connection status: a connection that needs re-authentication qualifies, and an authenticated one without a saved credential does not. Returns 404 for an unknown connection, and 409 when the connection is in another project, has no saved credential yet, or uses an external credential provider such as 1Password. No collection form is offered; managed auth collects the login. - `connection_id` string, required: ID of the managed auth connection whose saved credential this item reads. List connections with `GET /auth/connections`. - `description` string: Optional display text for the item, such as the site or service name. Set at creation and cannot be changed later; repeating the request with a different description returns 409. At most 16 KiB in UTF-8 bytes. - `provider` 'managed_auth', required - `type` 'credential', required ## Response `200` Existing matching item; card retries preserve identity and state - 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 - `201`: Item created - `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`: 14 breaking, 18 info - added `#/components/schemas/ShopPayCardState` to the `oneOf[#/components/schemas/CardVaultItem]/state` response property `oneOf` list for the response status `200` - added `#/components/schemas/ShopPayCardState` to the `oneOf[#/components/schemas/CardVaultItem]/state` response property `oneOf` list for the response status `201` - added `#/components/schemas/ShopPayCardVaultItemSpec` to the `oneOf[#/components/schemas/CardVaultItem]/spec` 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 `201` - …28 more - …earlier changes not shown [Operation history](https://skmtc.dev/onkernel/apis/kernel-api/changes/vaults/:id_or_name/items/:key/put.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)