> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-managed-auth-region.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create or retrieve an identical vault item by immutable key > 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 and card item types for credit cards and payment checkout instead. ## OpenAPI ````yaml https://api.onkernel.com/spec.json put /vaults/{id_or_name}/items/{key} openapi: 3.1.0 info: description: Developer tools and cloud infrastructure for AI agents to use web browsers title: Kernel API version: 0.1.0 servers: - description: API Server url: https://api.onkernel.com security: - bearerAuth: [] tags: - description: Create and manage browser sessions. name: Browsers - description: Control mouse, keyboard, and screen on the browser instance. name: Browser Computer Controls - description: Execute Playwright code against the browser instance. name: Browser Playwright - description: Discover and invoke native page tools across the browser instance. name: Browser WebMCP - description: Read, write, and manage files on the browser instance. name: Browser Filesystem - description: Execute and manage processes on the browser instance. name: Browser Processes - description: Record and manage browser session video replays. name: Browser Replays - description: Stream logs from the browser instance. name: Browser Logs - description: >- Stream live telemetry events from a browser session, and manage the destinations sessions export them to. name: Browser Telemetry - description: Create, list, retrieve, and delete browser profiles. name: Profiles - description: Create and manage proxy configurations for routing browser traffic. name: Proxies - description: Create, list, retrieve, and delete browser extensions. name: Extensions - description: Create and manage browser pools for acquiring and releasing browsers. name: Browser Pools - description: Inspect the identity and authorization context for the current request. name: Authentication - description: >- Create and manage auth connections for automated credential capture and login. name: Managed Auth - description: Create and manage credentials for authentication. name: Credentials - description: Configure external credential providers like 1Password. name: Credential Providers - description: List applications and versions. name: Apps - description: Create and manage app deployments and stream deployment events. name: Deployments - description: Invoke actions and stream or query invocation status and events. name: Invocations - description: Read and manage organization-level limits. name: Organization - description: | Create and manage projects for resource isolation within an organization. When projects are disabled for the organization, project operations return `404` with code `projects_disabled`. name: Projects - description: Create and manage API keys for organization and project-scoped access. name: API Keys - description: Read audit log records for the authenticated organization. name: Audit Logs - description: Resolve browser and proxy recommendations for bot-protected sites. name: Config Registry paths: /vaults/{id_or_name}/items/{key}: parameters: - in: path name: id_or_name required: true schema: type: string - in: path name: key required: true schema: maxLength: 255 minLength: 1 type: string put: tags: - Vaults summary: Create or retrieve an identical vault item by immutable key description: >- 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 and card item types for credit cards and payment checkout instead. operationId: putVaultItem requestBody: content: application/json: examples: agentcard_card: $ref: '#/components/examples/ExampleAgentCardCardInput' customer_managed_agentcard: summary: Create a wallet using customer-owned AgentCard credentials value: spec: provider: agentcard provider_config: name: my-agentcard type: wallet imported_link: summary: Import a grant from a customer-owned Link client value: spec: authorization: client: provider_config: name: my-link-client type: customer_managed method: oauth tokens: access_token: example-access-token refresh_token: example-refresh-token provider: link type: wallet kernel_managed_agentcard: summary: Start hosted enrollment with Kernel-managed credentials value: spec: provider: agentcard type: wallet kernel_managed_link: summary: Start Kernel-managed Link authorization value: spec: authorization: client: type: kernel_managed method: oauth provider: link type: wallet link_card: $ref: '#/components/examples/ExampleLinkCardInput' schema: $ref: '#/components/schemas/VaultItemRequest' required: true responses: '200': content: application/json: examples: agentcard_card: $ref: '#/components/examples/ExampleAgentCardCard' imported_link: $ref: '#/components/examples/ExampleImportedLinkWallet' link_card: $ref: '#/components/examples/ExampleLinkCard' schema: $ref: '#/components/schemas/VaultItem' description: Existing matching item; card retries preserve identity and state '201': content: application/json: examples: agentcard_card: $ref: '#/components/examples/ExampleAgentCardCard' customer_managed_agentcard: $ref: '#/components/examples/ExampleConfiguredAgentCardWallet' imported_link: $ref: '#/components/examples/ExampleImportedLinkWallet' kernel_managed_agentcard: $ref: '#/components/examples/ExampleManagedAgentCardWallet' kernel_managed_link: $ref: '#/components/examples/ExampleManagedLinkWallet' link_card: $ref: '#/components/examples/ExampleLinkCard' schema: $ref: '#/components/schemas/VaultItem' description: Item created '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: examples: ExampleAgentCardCardInput: summary: >- Create a reusable USD 25.99 card at key agentcard-card after its wallet connects value: spec: amount: 2599 card_id: vc_example currency: usd merchant: Example Store provider: agentcard wallet: agentcard-wallet type: card ExampleLinkCardInput: summary: Create a USD 25.99 request at key link-card after its wallet connects value: spec: amount: 2599 context: >- Purchase one notebook for USD 25.99 including shipping and taxes. This is a new order at Example Store, not a retry of an earlier payment. currency: usd merchant_name: Example Store merchant_url: https://store.example.com payment_method_id: pm_example provider: link wallet: link-wallet type: card ExampleAgentCardCard: summary: >- Ready AgentCard item with prepared checkout enabled. Alias values are synthetic. value: available_expansions: [] available_operations: - description: >- Prepare this unused AgentCard card before the first Square Pay action. POST to this item's operations endpoint with a body like {"type":"prepare_checkout","checkout":{"browser_id":"","merchant_origin":"https://shop.example.com","environment":"production"}}. Use the active browser session with this vault bound. merchant_origin is the top-level merchant document's origin, not the Square iframe. environment must be production or sandbox and describes Square, not the AgentCard credential mode. Deliver the returned approval URL and keep the approval page open. Poll the item until ready_to_submit, then submit native Pay before preparation.expires_at; readiness lasts at most 30 seconds. Unused preparations expire automatically. Preparation is single-use, including after failure or expiry. Do not automatically retry; reconcile uncertain outcomes with the merchant. type: prepare_checkout created_at: '2026-01-01T12:00:00Z' id: card_agentcard_example key: agentcard-card spec: amount: 2599 card_id: vc_example currency: usd merchant: Example Store provider: agentcard wallet: agentcard-wallet state: aliases: cvc: '123' exp_month: '12' exp_year: '2030' number: '4242424242424242' provider: agentcard status: ready type: card updated_at: '2026-01-01T12:00:00Z' ExampleImportedLinkWallet: summary: Connected imported grant; tokens are absent from the response value: available_expansions: - description: List funding methods available to this wallet. type: payment_methods available_operations: [] created_at: '2026-01-01T12:00:00Z' id: wallet_imported_example key: imported-wallet spec: authorization: client: provider_config: id: vpc_link_example type: customer_managed method: oauth provider: link state: provider: link status: connected type: wallet updated_at: '2026-01-01T12:00:00Z' ExampleLinkCard: summary: >- Requested Link card; identical PUT returns the same item without authorization value: available_expansions: [] available_operations: - description: Request cardholder approval for this payment. type: authorize created_at: '2026-01-01T12:00:00Z' id: card_link_example key: link-card spec: amount: 2599 context: >- Purchase one notebook for USD 25.99 including shipping and taxes. This is a new order at Example Store, not a retry of an earlier payment. currency: usd merchant_name: Example Store merchant_url: https://store.example.com payment_method_id: pm_example provider: link wallet: link-wallet state: provider: link status: requested type: card updated_at: '2026-01-01T12:00:00Z' ExampleConfiguredAgentCardWallet: summary: Hosted enrollment using a customer-owned configuration value: action: name: card_enrollment url: https://example.com/card-enrollment available_expansions: [] available_operations: [] created_at: '2026-01-01T12:00:00Z' expires_at: '2026-01-01T13:00:00Z' id: wallet_agentcard_example key: agentcard-wallet spec: provider: agentcard provider_config: id: vpc_agentcard_example state: provider: agentcard status: pending_authorization type: wallet updated_at: '2026-01-01T12:00:00Z' ExampleManagedAgentCardWallet: summary: >- Hosted enrollment using Kernel-managed credentials at key agentcard-wallet value: action: name: card_enrollment url: https://example.com/card-enrollment available_expansions: [] available_operations: [] created_at: '2026-01-01T12:00:00Z' expires_at: '2026-01-01T13:00:00Z' id: wallet_managed_agentcard_example key: agentcard-wallet spec: provider: agentcard state: provider: agentcard status: pending_authorization type: wallet updated_at: '2026-01-01T12:00:00Z' ExampleManagedLinkWallet: summary: Pending OAuth through Kernel-managed credentials at key link-wallet value: action: name: link_oauth url: https://example.com/link-authorization available_expansions: [] available_operations: [] created_at: '2026-01-01T12:00:00Z' expires_at: '2026-01-01T12:10:00Z' id: wallet_link_example key: link-wallet spec: authorization: client: type: kernel_managed method: oauth provider: link state: provider: link status: pending_authorization type: wallet updated_at: '2026-01-01T12:00:00Z' schemas: VaultItemRequest: discriminator: mapping: card: $ref: '#/components/schemas/CardVaultItemRequest' credential: $ref: '#/components/schemas/CredentialVaultItemRequest' wallet: $ref: '#/components/schemas/WalletVaultItemRequest' propertyName: type oneOf: - $ref: '#/components/schemas/WalletVaultItemRequest' - $ref: '#/components/schemas/CardVaultItemRequest' - $ref: '#/components/schemas/CredentialVaultItemRequest' VaultItem: discriminator: mapping: card: $ref: '#/components/schemas/CardVaultItem' credential: $ref: '#/components/schemas/CredentialVaultItem' wallet: $ref: '#/components/schemas/WalletVaultItem' propertyName: type oneOf: - $ref: '#/components/schemas/WalletVaultItem' - $ref: '#/components/schemas/CardVaultItem' - $ref: '#/components/schemas/CredentialVaultItem' CardVaultItemRequest: additionalProperties: false properties: spec: $ref: '#/components/schemas/CardVaultItemSpec' type: enum: - card type: string required: - type - spec type: object CredentialVaultItemRequest: additionalProperties: false description: > Create a credential item without a wallet or external provider. 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 and card item types for credit cards and payment checkout instead. If all required fields have values, return ready without a collection action; collect can still open its form. Otherwise return pending_collection with a time-scoped Kernel-hosted collection action. Missing optional fields alone do not trigger collection. Repeating the original creation request returns the current item without overwriting later edits; a different request at the same key returns 409. Use PATCH for updates. Required totp fields must include a valid seed on creation; otherwise return 400 rather than opening a form that cannot collect it. Optional totp fields may be unset and populated later through PATCH. properties: spec: $ref: '#/components/schemas/CredentialVaultItemSpecInput' type: enum: - credential type: string required: - type - spec type: object WalletVaultItemRequest: additionalProperties: false properties: spec: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardWalletVaultItemSpec' link: $ref: '#/components/schemas/LinkWalletVaultItemRequestSpec' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkWalletVaultItemRequestSpec' - $ref: '#/components/schemas/AgentCardWalletVaultItemSpec' type: enum: - wallet type: string required: - type - spec type: object CardVaultItem: additionalProperties: false properties: action: $ref: '#/components/schemas/VaultItemAction' available_expansions: items: $ref: '#/components/schemas/AvailableVaultItemExpansion' type: array available_operations: items: $ref: '#/components/schemas/AvailableVaultItemOperation' type: array created_at: format: date-time type: string expires_at: format: date-time type: string id: type: string key: description: Immutable item key assigned when the item is created. type: string spec: $ref: '#/components/schemas/CardVaultItemSpec' state: $ref: '#/components/schemas/CardVaultItemState' type: enum: - card type: string updated_at: format: date-time type: string required: - id - key - type - spec - state - available_operations - available_expansions - created_at - updated_at type: object CredentialVaultItem: additionalProperties: false properties: action: $ref: '#/components/schemas/CredentialCollectionAction' available_expansions: items: $ref: '#/components/schemas/AvailableVaultItemExpansion' maxItems: 0 type: array available_operations: description: >- Advertises collect for ready and pending_collection items. Browser fill is advertised only when separately implemented and eligible. items: $ref: '#/components/schemas/AvailableVaultItemOperation' type: array created_at: format: date-time type: string id: type: string key: description: Immutable item key assigned when the item is created. type: string spec: $ref: '#/components/schemas/CredentialVaultItemSpec' state: $ref: '#/components/schemas/CredentialVaultItemState' type: enum: - credential type: string updated_at: format: date-time type: string version: description: >- Starts at 1 and increments on PATCH and successful hosted submission, but not collection-link renewal. minimum: 1 type: integer required: - id - key - type - version - spec - state - available_operations - available_expansions - created_at - updated_at type: object WalletVaultItem: additionalProperties: false properties: action: $ref: '#/components/schemas/VaultItemAction' available_expansions: items: $ref: '#/components/schemas/AvailableVaultItemExpansion' type: array available_operations: items: $ref: '#/components/schemas/AvailableVaultItemOperation' type: array created_at: format: date-time type: string expanded: $ref: '#/components/schemas/VaultItemExpanded' expires_at: format: date-time type: string id: type: string key: description: Immutable item key assigned when the item is created. type: string spec: $ref: '#/components/schemas/WalletVaultItemSpec' state: $ref: '#/components/schemas/WalletVaultItemState' type: enum: - wallet type: string updated_at: format: date-time type: string required: - id - key - type - spec - state - available_operations - available_expansions - created_at - updated_at type: object Error: properties: code: description: Application-specific error code (machine-readable) example: bad_request type: string details: description: Additional error details (for multiple errors) items: $ref: '#/components/schemas/ErrorDetail' type: array inner_error: $ref: '#/components/schemas/ErrorDetail' message: description: Human-readable error description for debugging example: 'Missing required field: app_name' type: string required: - code - message type: object CardVaultItemSpec: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardCardVaultItemSpec' link: $ref: '#/components/schemas/LinkCardVaultItemSpec' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkCardVaultItemSpec' - $ref: '#/components/schemas/AgentCardCardVaultItemSpec' CredentialVaultItemSpecInput: additionalProperties: false description: >- Credential fields are for login and other non-payment credentials. Do not store, collect, or fill credit card data in credential items. Use wallet and card item types for credit cards and payment checkout instead. properties: description: description: >- 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. maxLength: 16384 type: string fields: additionalProperties: $ref: '#/components/schemas/CredentialVaultFieldInput' maxProperties: 32 minProperties: 1 propertyNames: pattern: ^[a-zA-Z][a-zA-Z0-9_]{0,63}$ type: object required: - fields type: object AgentCardWalletVaultItemSpec: additionalProperties: false description: >- 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. user_id may only reference a user already enrolled by a wallet in this organization under the same configuration. properties: provider: enum: - agentcard type: string provider_config: $ref: '#/components/schemas/VaultProviderConfigReference' description: >- Select an AgentCard configuration. The wallet's configuration cannot be changed after creation. user_id: pattern: ^usr_[A-Za-z0-9_]+$ type: string required: - provider type: object LinkWalletVaultItemRequestSpec: additionalProperties: false properties: authorization: oneOf: - $ref: '#/components/schemas/KernelManagedLinkAuthorizationInput' - $ref: '#/components/schemas/ImportedLinkAuthorizationInput' provider: enum: - link type: string required: - provider - authorization type: object VaultItemAction: discriminator: mapping: card_enrollment: $ref: '#/components/schemas/CardEnrollmentAction' collect: $ref: '#/components/schemas/CollectAction' embedded_ceremony: $ref: '#/components/schemas/EmbeddedCeremonyAction' link_oauth: $ref: '#/components/schemas/LinkOAuthAction' mfa: $ref: '#/components/schemas/MfaAction' push_approval: $ref: '#/components/schemas/PushApprovalAction' spend_approval: $ref: '#/components/schemas/SpendApprovalAction' propertyName: name oneOf: - $ref: '#/components/schemas/LinkOAuthAction' - $ref: '#/components/schemas/SpendApprovalAction' - $ref: '#/components/schemas/PushApprovalAction' - $ref: '#/components/schemas/CollectAction' - $ref: '#/components/schemas/MfaAction' - $ref: '#/components/schemas/EmbeddedCeremonyAction' - $ref: '#/components/schemas/CardEnrollmentAction' AvailableVaultItemExpansion: additionalProperties: false description: >- Live data that can currently be requested by passing its type to the item GET expand parameter. properties: description: type: string type: $ref: '#/components/schemas/VaultItemExpansionType' required: - type - description type: object AvailableVaultItemOperation: additionalProperties: false description: >- An operation that is currently valid for this item. Read the description before invoking it through the item operations endpoint. properties: description: type: string type: $ref: '#/components/schemas/VaultItemOperationType' required: - type - description type: object CardVaultItemState: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardCardState' link: $ref: '#/components/schemas/LinkCardState' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkCardState' - $ref: '#/components/schemas/AgentCardCardState' CredentialCollectionAction: additionalProperties: false description: > One schema-derived form for the item, available in ready or pending_collection state. Render every form-supported field as editable; omit totp fields and preserve their stored seeds. 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 edits; seed writes require the ordinary authenticated item API. Customer forms likewise omit totp 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. properties: expires_at: description: >- Expiry of the Kernel-hosted collection link (30 minutes after issuance). format: date-time type: string name: enum: - collect type: string url: description: >- Time-scoped hosted form URL (vault.kernel.sh in production). Open this URL as returned; treat it as a secret. format: uri type: string required: - name - url - expires_at type: object CredentialVaultItemSpec: additionalProperties: false properties: description: description: >- 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. maxLength: 16384 type: string fields: additionalProperties: $ref: '#/components/schemas/CredentialVaultFieldDefinition' maxProperties: 32 minProperties: 1 type: object required: - fields type: object CredentialVaultItemState: additionalProperties: false properties: fields: additionalProperties: $ref: '#/components/schemas/CredentialVaultFieldState' description: Exactly one entry for each declared field. minProperties: 1 type: object status: description: >- Ready means all required fields have values, not that a login succeeded. Optional fields may remain unset. enum: - pending_collection - ready type: string required: - status - fields type: object VaultItemExpanded: additionalProperties: false description: >- Live, non-persisted data requested through the item GET expand parameter. properties: payment_methods: items: $ref: '#/components/schemas/VaultPaymentMethod' type: array type: object WalletVaultItemSpec: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardWalletVaultItemSpec' link: $ref: '#/components/schemas/LinkWalletVaultItemSpec' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkWalletVaultItemSpec' - $ref: '#/components/schemas/AgentCardWalletVaultItemSpec' WalletVaultItemState: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardWalletState' link: $ref: '#/components/schemas/LinkWalletState' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkWalletState' - $ref: '#/components/schemas/AgentCardWalletState' ErrorDetail: properties: code: description: Lower-level error code providing more specific detail example: invalid_input type: string message: description: Further detail about the error example: Provided version string is not semver compliant type: string type: object AgentCardCardVaultItemSpec: additionalProperties: false description: >- AgentCard reusable live payment card. Test-mode card creation is not supported. Each checkout creates an approval-gated authorization for spec.merchant / spec.amount. The card stays ready after each authorization. properties: amount: description: Integer amount in minor currency units. format: int64 maximum: 9007199254740991 minimum: 1 type: integer card_id: description: >- AgentCard vaulted card to pay with. Omitted, the cardholder picks on the approval screen. pattern: ^vc_[A-Za-z0-9_]+$ type: string currency: maxLength: 3 minLength: 3 pattern: ^[A-Za-z]{3}$ type: string merchant: description: Merchant name shown on the cardholder's approval screen. maxLength: 120 minLength: 1 type: string provider: enum: - agentcard type: string wallet: description: Wallet item key used to authorize checkouts. type: string required: - provider - wallet - merchant - amount - currency type: object LinkCardVaultItemSpec: additionalProperties: false description: Live payment card. Test-mode card creation is not supported. properties: amount: description: Integer amount in minor currency units. maximum: 500000 minimum: 1 type: integer context: minLength: 100 type: string currency: maxLength: 3 minLength: 3 pattern: ^[A-Za-z]{3}$ type: string expires_at: format: int64 type: integer line_items: items: $ref: '#/components/schemas/LinkLineItem' type: array merchant_name: maxLength: 255 minLength: 1 type: string merchant_url: format: uri type: string metadata: additionalProperties: type: string type: object payment_method_id: description: >- 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. minLength: 1 type: string provider: enum: - link type: string totals: items: $ref: '#/components/schemas/LinkTotal' type: array wallet: description: Wallet item key used to mint this card. type: string required: - provider - wallet - payment_method_id - amount - currency - merchant_name - merchant_url - context type: object CredentialVaultFieldInput: additionalProperties: false properties: required: default: true type: boolean sensitive: default: true description: >- 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 and totp 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: boolean type: $ref: '#/components/schemas/CredentialVaultFieldType' value: description: >- 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. maxLength: 16384 minLength: 1 type: string writeOnly: true required: - type type: object VaultProviderConfigReference: additionalProperties: false description: >- Select a provider config by ID or name. Responses return the ID. Renaming a config does not change existing wallet bindings; a wallet cannot switch to a different config after creation. oneOf: - required: - id - required: - name properties: id: minLength: 1 type: string name: pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string type: object KernelManagedLinkAuthorizationInput: additionalProperties: false description: Kernel starts and completes the user's Link authorization flow. properties: client: $ref: '#/components/schemas/KernelManagedOAuthClient' method: enum: - oauth type: string required: - method - client type: object ImportedLinkAuthorizationInput: additionalProperties: false description: >- 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. properties: client: $ref: '#/components/schemas/CustomerManagedOAuthClient' method: enum: - oauth type: string tokens: allOf: - $ref: '#/components/schemas/LinkWalletTokenInput' writeOnly: true required: - method - client - tokens type: object CardEnrollmentAction: additionalProperties: false properties: name: enum: - card_enrollment type: string url: format: uri type: string required: - name - url type: object CollectAction: additionalProperties: false properties: name: enum: - collect type: string required: - name type: object EmbeddedCeremonyAction: additionalProperties: false properties: name: enum: - embedded_ceremony type: string required: - name type: object LinkOAuthAction: additionalProperties: false properties: name: enum: - link_oauth type: string url: format: uri type: string required: - name - url type: object MfaAction: additionalProperties: false properties: name: enum: - mfa type: string required: - name type: object PushApprovalAction: additionalProperties: false properties: name: enum: - push_approval type: string required: - name type: object SpendApprovalAction: additionalProperties: false properties: name: enum: - spend_approval type: string url: format: uri type: string required: - name - url type: object VaultItemExpansionType: enum: - payment_methods type: string VaultItemOperationType: enum: - authorize - collect - prepare_checkout - fill type: string AgentCardCardState: additionalProperties: false properties: aliases: $ref: '#/components/schemas/VaultCardAliases' authorization: $ref: '#/components/schemas/AgentCardCheckoutAuthorization' masks: $ref: '#/components/schemas/VaultItemMasks' preparation: $ref: '#/components/schemas/AgentCardCheckoutPreparation' provider: enum: - agentcard type: string status: description: >- 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. enum: - requested - ready - preparing - ready_to_submit - pending_approval - consumed - stopped - outcome_unknown - degraded - recovery_required type: string status_reason: type: string required: - provider - status type: object LinkCardState: additionalProperties: false properties: aliases: $ref: '#/components/schemas/VaultCardAliases' domains: items: type: string type: array masks: $ref: '#/components/schemas/VaultItemMasks' provider: enum: - link type: string status: description: >- recovery_required means an original provider operation has an unresolved outcome. Do not retry, delete, or replace it. Known references may be observed safely, but unknown creation without an ID and uncertain card-material retrieval require manual reconciliation with the provider or support. There is no reset or caller-asserted reconciliation operation. enum: - requested - pending_authorization - ready - consumed - expired - declined - recovery_required type: string status_reason: type: string required: - provider - status type: object CredentialVaultFieldDefinition: additionalProperties: false properties: required: description: >- Whether a nonempty value is required for readiness and form submission. type: boolean sensitive: description: >- 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: boolean type: $ref: '#/components/schemas/CredentialVaultFieldType' required: - type - required - sensitive type: object CredentialVaultFieldState: additionalProperties: false properties: has_value: type: boolean value: description: >- Present exactly when has_value is true and the field is not sensitive. Reflects the latest developer or human edit. For totp, has_value indicates a stored seed; neither the seed nor a generated code is returned. minLength: 1 type: string required: - has_value type: object VaultPaymentMethod: additionalProperties: false properties: capabilities: $ref: '#/components/schemas/VaultPaymentMethodCapabilities' display: $ref: '#/components/schemas/VaultPaymentMethodDisplay' id: type: string is_default: type: boolean provider: description: Provider that issued this payment-method ID. type: string type: description: Provider-neutral payment-method type normalized to lowercase. type: string required: - id - provider - type - is_default - display - capabilities type: object LinkWalletVaultItemSpec: additionalProperties: false properties: authorization: $ref: '#/components/schemas/LinkOAuthAuthorization' provider: enum: - link type: string required: - provider - authorization type: object AgentCardWalletState: additionalProperties: false properties: provider: enum: - agentcard type: string status: enum: - pending_authorization - connected - degraded type: string status_reason: type: string user_id: description: AgentCard user id linked to this wallet. Present once connected. type: string required: - provider - status type: object LinkWalletState: additionalProperties: false properties: provider: enum: - link type: string status: enum: - pending_authorization - connected - declined - reconnect_required - degraded type: string status_reason: type: string required: - provider - status type: object LinkLineItem: additionalProperties: false properties: description: type: string image_url: type: string name: type: string product_url: type: string quantity: minimum: 1 type: integer sku: type: string totals: items: $ref: '#/components/schemas/LinkTotal' type: array unit_amount: description: Unit amount in minor currency units. type: integer url: type: string required: - name type: object LinkTotal: additionalProperties: false properties: amount: description: Total amount in minor currency units. type: integer display_text: type: string type: type: string required: - type - display_text - amount type: object CredentialVaultFieldType: description: > Text, email, and password have form inputs; totp does not and is omitted from both Kernel-hosted and customer React forms. Password and totp 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. enum: - text - email - password - totp type: string KernelManagedOAuthClient: additionalProperties: false properties: type: enum: - kernel_managed type: string required: - type type: object CustomerManagedOAuthClient: additionalProperties: false properties: provider_config: $ref: '#/components/schemas/VaultProviderConfigReference' type: enum: - customer_managed type: string required: - type - provider_config type: object LinkWalletTokenInput: additionalProperties: false description: >- 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. properties: access_token: minLength: 1 type: string writeOnly: true refresh_token: minLength: 1 type: string writeOnly: true required: - access_token - refresh_token type: object VaultCardAliases: additionalProperties: false properties: cvc: pattern: ^\d{3}$ type: string exp_month: pattern: ^\d{2}$ type: string exp_year: pattern: ^\d{4}$ type: string number: pattern: ^\d{16}$ type: string readOnly: true required: - number - cvc - exp_month - exp_year type: object AgentCardCheckoutAuthorization: additionalProperties: false description: >- The in-flight or most recent checkout authorization. Present while a checkout is pending approval and after it settles. properties: actual_cents: format: int64 type: integer amount: description: Display amount shown on the approval screen. type: string amount_authority: enum: - display_only - stripe_payment_intent type: string amount_cents: format: int64 type: integer amount_verified: type: boolean approval_url: format: uri type: string browser_id: description: Browser session that submitted the checkout. type: string charged_amount_cents: format: int64 type: integer charged_currency: type: string charged_kind: enum: - captured - authorized - none type: string created_at: format: date-time type: string currency: type: string expected_cents: format: int64 type: integer expires_at: format: date-time type: string id: type: string merchant: type: string psp: type: string psp_error_code: type: string reason: type: string replay_attempted: type: boolean replay_delivered: description: Whether the processor response was delivered to the browser. type: boolean replay_status: description: HTTP status of the replayed processor response. type: integer status: enum: - awaiting_approval - approved - declined - expired type: string required: - id - status - psp - merchant - amount_cents - currency - created_at type: object VaultItemMasks: additionalProperties: type: string properties: brand: type: string last4: maxLength: 4 minLength: 4 type: string type: object AgentCardCheckoutPreparation: additionalProperties: false description: >- One-use Square checkout preparation. Keep the approval page open through token handoff. The amount is display-only and does not constrain the merchant's eventual charge. properties: approval_url: format: uri type: string browser_id: type: string created_at: format: date-time type: string environment: enum: - production - sandbox type: string expires_at: description: >- 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. format: date-time type: string id: type: string merchant_origin: type: string status: description: >- 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. enum: - creating - awaiting_approval - ready - consumed - cancelled - expired - unknown type: string required: - status - browser_id - merchant_origin - environment - created_at type: object VaultPaymentMethodCapabilities: additionalProperties: false description: >- Provider-reported advisory capabilities. A missing capability is unknown, not ineligible; only eligible=false is an explicit negative signal. properties: single_use_card: $ref: '#/components/schemas/VaultPaymentMethodCapability' type: object VaultPaymentMethodDisplay: additionalProperties: false properties: brand: type: string label: type: string last4: type: string type: object LinkOAuthAuthorization: additionalProperties: false properties: client: $ref: '#/components/schemas/LinkOAuthClient' method: enum: - oauth type: string required: - method - client type: object VaultPaymentMethodCapability: additionalProperties: false properties: eligible: type: boolean reasons: items: type: string type: array required: - eligible - reasons type: object LinkOAuthClient: discriminator: mapping: customer_managed: $ref: '#/components/schemas/CustomerManagedOAuthClient' kernel_managed: $ref: '#/components/schemas/KernelManagedOAuthClient' propertyName: type oneOf: - $ref: '#/components/schemas/KernelManagedOAuthClient' - $ref: '#/components/schemas/CustomerManagedOAuthClient' responses: BadRequest: content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad Request – invalid input Unauthorized: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unauthorized – missing or invalid authorization token NotFound: content: application/json: schema: $ref: '#/components/schemas/Error' description: Resource not found Conflict: content: application/json: schema: $ref: '#/components/schemas/Error' description: Conflict – resource already exists InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error securitySchemes: bearerAuth: scheme: bearer type: http ````