Perform an operation advertised by a vault item
Retrieve the item first and invoke only an operation listed in
available_operations, following its natural-language description.
Availability is rechecked at execution time; unavailable operations return 409.
Authorization and preparation may call an external provider and return updated state.
Link cards advertise authorize; pass browser_id and page_url from the final
checkout page so Kernel can inspect the checkout. Eligible unused
AgentCard cards advertise prepare_checkout, which requires checkout context
and obtains device approval before native Square Pay. Keep the returned
approval page open, poll until ready_to_submit, then submit before
preparation.expires_at. Unused preparations expire automatically and cannot
be reused. If spend-request creation is rejected with a non-retryable
provider error, the card item is deleted and the provider’s error code and
message are returned. Rate limits return HTTP 429 and retain the card item;
stop, back off, and retry the same authorize operation.
Ready Kernel cards advertise fill. Fill delivers card details for a few minutes; submit checkout promptly after filling. A repeated fill is safe.
Fill returns a value-free execution result. Validation failures before
writing return 400 (invalid request or targets), 403 (access or destination
denied), 404 (resource not found), or 409 (item or browser not ready).
Once writing starts, known partial failures and indeterminate field outcomes
return 200 with status failed or unknown. Fill never submits the page, so
it is safe to retry after a failure, an unknown outcome, or a transport error.
Connected Kernel wallets may advertise add_payment_method, which returns a single-use hosted card_enrollment link for a card, and remove_payment_method, which removes one card without affecting the others. Both operations require vaults:write in addition to vaults:use on the vault for scoped API keys, and return 403 without both permissions.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
- Option 13
- Option 14
- Option 15
- Option 16
- Option 17
Authorize a Link, Kernel or Shop Pay card using its existing purchase specification. Use only after explicit user approval and when the item advertises authorize; follow the advertised operation's description. For a Link or Shop Pay card, pass browser_id and page_url together while the browser is on the final checkout page: Kernel confirms that checkout is open, sends it to the provider as the merchant, and limits fill to that checkout's origin in any browser with this vault attached. For Link it also chooses how the credential is delivered. Omitting both issues a virtual card that fills any page on the merchant origin. Once approval has been requested, browser_id and page_url are ignored and authorize only re-checks the request. Browser and checkout inspection errors occur before any provider request and can be retried once the browser is on the checkout page. Kernel cards do not accept browser_id or page_url.
authorize Browser session ID, not a reusable browser name. The browser must have this vault attached.
1Exact current top-level URL of the final checkout page open in browser_id.
^https://[^/?#@*\s]+(?:[/?#][^\s]*)?$Response
Authorization or preparation completed or resumed, or fill execution outcomes returned
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
Authorization and preparation return the existing item shape. Fill and passkey operations return value-free results; WebMCP invocation returns the tool's output. None persist transient outcomes on the item. Payment-method operations return the affected wallet payment method.
Immutable item key assigned when the item is created.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 1
- Option 2
- Option 3
- Option 4
wallet - Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
Server-generated provider and lifecycle guidance for agents.
Live, non-persisted data requested through the item GET expand parameter.