feat: Let customers keep refreshing imported Link wallet grants

Stainless-Generated-From: 97ae6043e5c5ede83741602c06c8d6931c09fefd

Author: kernel-internal[bot]

src/kernel/resources/vaults/items.py

@@ -1424,6 +1424,67 @@ def perform_operation(
         """
         ...
 
+    @overload
+    def perform_operation(
+        self,
+        key: str,
+        *,
+        id_or_name: str,
+        access_token: str,
+        type: Literal["update_access_token"],
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+        idempotency_key: str | None = None,
+    ) -> VaultItemOperationResponse:
+        """
+        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.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+
+          idempotency_key: Specify a custom idempotency key for this request
+        """
+        ...
+
     @overload
     def perform_operation(
         self,
@@ -1656,6 +1717,7 @@ def perform_operation(
         | Literal["1pw_fill"]
         | Literal["1pw_recover"]
         | Literal["1pw_update_access_token"]
+        | Literal["update_access_token"]
         | Literal["webmcp_invoke"]
         | Literal["add_payment_method"]
         | Literal["remove_payment_method"],
@@ -3429,6 +3491,67 @@ async def perform_operation(
         """
         ...
 
+    @overload
+    async def perform_operation(
+        self,
+        key: str,
+        *,
+        id_or_name: str,
+        access_token: str,
+        type: Literal["update_access_token"],
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+        idempotency_key: str | None = None,
+    ) -> VaultItemOperationResponse:
+        """
+        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.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+
+          idempotency_key: Specify a custom idempotency key for this request
+        """
+        ...
+
     @overload
     async def perform_operation(
         self,
@@ -3661,6 +3784,7 @@ async def perform_operation(
         | Literal["1pw_fill"]
         | Literal["1pw_recover"]
         | Literal["1pw_update_access_token"]
+        | Literal["update_access_token"]
         | Literal["webmcp_invoke"]
         | Literal["add_payment_method"]
         | Literal["remove_payment_method"],

src/kernel/types/vaults/credential_account_vault_item.py

@@ -45,6 +45,7 @@ class AvailableOperation(BaseModel):
         "1pw_fill",
         "1pw_recover",
         "1pw_update_access_token",
+        "update_access_token",
         "webmcp_invoke",
         "add_payment_method",
         "remove_payment_method",

src/kernel/types/vaults/credential_vault_item.py

@@ -52,6 +52,7 @@ class AvailableOperation(BaseModel):
         "1pw_fill",
         "1pw_recover",
         "1pw_update_access_token",
+        "update_access_token",
         "webmcp_invoke",
         "add_payment_method",
         "remove_payment_method",

src/kernel/types/vaults/item_perform_operation_params.py

@@ -28,6 +28,7 @@
     "OnePasswordFillVaultItemOperationRequest",
     "OnePasswordRecoverVaultItemOperationRequest",
     "OnePasswordUpdateAccessTokenVaultItemOperationRequest",
+    "UpdateAccessTokenVaultItemOperationRequest",
     "WebmcpInvokeVaultItemOperationRequest",
     "AddPaymentMethodVaultItemOperationRequest",
     "RemovePaymentMethodVaultItemOperationRequest",
@@ -267,6 +268,14 @@ class OnePasswordUpdateAccessTokenVaultItemOperationRequest(TypedDict, total=Fal
     """Optional supplied expiry. Omit to clear the old expiry."""
 
 
+class UpdateAccessTokenVaultItemOperationRequest(TypedDict, total=False):
+    id_or_name: Required[str]
+
+    access_token: Required[str]
+
+    type: Required[Literal["update_access_token"]]
+
+
 class WebmcpInvokeVaultItemOperationRequest(TypedDict, total=False):
     id_or_name: Required[str]
 
@@ -330,6 +339,7 @@ class RemovePaymentMethodVaultItemOperationRequest(TypedDict, total=False):
     OnePasswordFillVaultItemOperationRequest,
     OnePasswordRecoverVaultItemOperationRequest,
     OnePasswordUpdateAccessTokenVaultItemOperationRequest,
+    UpdateAccessTokenVaultItemOperationRequest,
     WebmcpInvokeVaultItemOperationRequest,
     AddPaymentMethodVaultItemOperationRequest,
     RemovePaymentMethodVaultItemOperationRequest,

src/kernel/types/vaults/item_upsert_params.py

@@ -107,14 +107,15 @@ class WalletVaultItemRequestSpecLinkWalletVaultItemRequestSpecAuthorizationImpor
 class WalletVaultItemRequestSpecLinkWalletVaultItemRequestSpecAuthorizationImportedLinkAuthorizationInputTokens(
     TypedDict, total=False
 ):
-    """Send the token pair from your backend.
+    """Send the tokens 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.
+    Supply a currently valid access token. With token_refresh=kernel, also send the refresh token from the same Link grant under the referenced client; Kernel refreshes when needed after import and uses the expiry returned by Link for subsequent tokens. With token_refresh=customer, omit the refresh token. Tokens are never returned in wallet responses, events, or logs.
     """
 
     access_token: Required[str]
 
-    refresh_token: Required[str]
+    refresh_token: str
+    """Required with token_refresh=kernel; rejected with token_refresh=customer."""
 
 
 class WalletVaultItemRequestSpecLinkWalletVaultItemRequestSpecAuthorizationImportedLinkAuthorizationInput(
@@ -123,7 +124,8 @@ class WalletVaultItemRequestSpecLinkWalletVaultItemRequestSpecAuthorizationImpor
     """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.
+    By default (token_refresh=kernel), Kernel owns subsequent refresh-token rotation after a successful import; the customer must stop refreshing this grant. With token_refresh=customer, send only the access token: your backend keeps the refresh token and rotates the grant, and Kernel never refreshes or revokes it. Replace the stored access token with the wallet's update_access_token operation before each step that reaches Link, such as creating, authorizing or filling a card. When Link rejects the stored access token, operations return 409 without contacting Link again; update the token and retry. The remainder of this description applies to token_refresh=kernel.
+    With token_refresh=kernel, 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.
     """
@@ -137,12 +139,22 @@ class WalletVaultItemRequestSpecLinkWalletVaultItemRequestSpecAuthorizationImpor
     tokens: Required[
         WalletVaultItemRequestSpecLinkWalletVaultItemRequestSpecAuthorizationImportedLinkAuthorizationInputTokens
     ]
-    """Send the token pair from your backend.
+    """Send the tokens 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.
+    Supply a currently valid access token. With token_refresh=kernel, also send the
+    refresh token from the same Link grant under the referenced client; Kernel
+    refreshes when needed after import and uses the expiry returned by Link for
+    subsequent tokens. With token_refresh=customer, omit the refresh token. Tokens
+    are never returned in wallet responses, events, or logs.
+    """
+
+    token_refresh: Literal["kernel", "customer"]
+    """Who refreshes an imported Link grant.
+
+    kernel (default) means Kernel holds and rotates the refresh token. customer
+    means your backend keeps the refresh token and replaces the access token with
+    update_access_token; Kernel never refreshes or revokes the grant. Fixed at
+    wallet creation.
     """
 
 

src/kernel/types/vaults/payment_request_vault_item.py

@@ -45,6 +45,7 @@ class AvailableOperation(BaseModel):
         "1pw_fill",
         "1pw_recover",
         "1pw_update_access_token",
+        "update_access_token",
         "webmcp_invoke",
         "add_payment_method",
         "remove_payment_method",

src/kernel/types/vaults/vault_item.py

@@ -63,6 +63,7 @@ class WalletVaultItemAvailableOperation(BaseModel):
         "1pw_fill",
         "1pw_recover",
         "1pw_update_access_token",
+        "update_access_token",
         "webmcp_invoke",
         "add_payment_method",
         "remove_payment_method",
@@ -170,6 +171,7 @@ class CardVaultItemAvailableOperation(BaseModel):
         "1pw_fill",
         "1pw_recover",
         "1pw_update_access_token",
+        "update_access_token",
         "webmcp_invoke",
         "add_payment_method",
         "remove_payment_method",

src/kernel/types/vaults/vault_item_operation_response.py

@@ -68,6 +68,7 @@ class WalletVaultItemAvailableOperation(BaseModel):
         "1pw_fill",
         "1pw_recover",
         "1pw_update_access_token",
+        "update_access_token",
         "webmcp_invoke",
         "add_payment_method",
         "remove_payment_method",
@@ -175,6 +176,7 @@ class CardVaultItemAvailableOperation(BaseModel):
         "1pw_fill",
         "1pw_recover",
         "1pw_update_access_token",
+        "update_access_token",
         "webmcp_invoke",
         "add_payment_method",
         "remove_payment_method",

src/kernel/types/vaults/wallet_vault_item_spec.py

@@ -61,6 +61,15 @@ class LinkWalletVaultItemSpecAuthorization(BaseModel):
 
     method: Literal["oauth"]
 
+    token_refresh: Optional[Literal["kernel", "customer"]] = None
+    """Who refreshes an imported Link grant.
+
+    kernel (default) means Kernel holds and rotates the refresh token. customer
+    means your backend keeps the refresh token and replaces the access token with
+    update_access_token; Kernel never refreshes or revokes the grant. Fixed at
+    wallet creation.
+    """
+
 
 class LinkWalletVaultItemSpec(BaseModel):
     authorization: LinkWalletVaultItemSpecAuthorization