Skip to content

Commit 49af4e9

Browse files
feat: Let customers keep refreshing imported Link wallet grants
Stainless-Generated-From: f6b9fb6b4812bb81fd65c6f560ac1b536437b77c
1 parent 05a01e6 commit 49af4e9

1 file changed

Lines changed: 83 additions & 29 deletions

File tree

‎src/resources/vaults/items.ts‎

Lines changed: 83 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -863,6 +863,7 @@ export namespace CredentialAccountVaultItem {
863863
| '1pw_fill'
864864
| '1pw_recover'
865865
| '1pw_update_access_token'
866+
| 'update_access_token'
866867
| 'webmcp_invoke'
867868
| 'add_payment_method'
868869
| 'remove_payment_method';
@@ -1243,6 +1244,7 @@ export namespace CredentialVaultItem {
12431244
| '1pw_fill'
12441245
| '1pw_recover'
12451246
| '1pw_update_access_token'
1247+
| 'update_access_token'
12461248
| 'webmcp_invoke'
12471249
| 'add_payment_method'
12481250
| 'remove_payment_method';
@@ -2677,6 +2679,7 @@ export namespace PaymentRequestVaultItem {
26772679
| '1pw_fill'
26782680
| '1pw_recover'
26792681
| '1pw_update_access_token'
2682+
| 'update_access_token'
26802683
| 'webmcp_invoke'
26812684
| 'add_payment_method'
26822685
| 'remove_payment_method';
@@ -3402,6 +3405,7 @@ export namespace VaultItem {
34023405
| '1pw_fill'
34033406
| '1pw_recover'
34043407
| '1pw_update_access_token'
3408+
| 'update_access_token'
34053409
| 'webmcp_invoke'
34063410
| 'add_payment_method'
34073411
| 'remove_payment_method';
@@ -3501,6 +3505,7 @@ export namespace VaultItem {
35013505
| '1pw_fill'
35023506
| '1pw_recover'
35033507
| '1pw_update_access_token'
3508+
| 'update_access_token'
35043509
| 'webmcp_invoke'
35053510
| 'add_payment_method'
35063511
| 'remove_payment_method';
@@ -3692,6 +3697,7 @@ export namespace VaultItemOperationResponse {
36923697
| '1pw_fill'
36933698
| '1pw_recover'
36943699
| '1pw_update_access_token'
3700+
| 'update_access_token'
36953701
| 'webmcp_invoke'
36963702
| 'add_payment_method'
36973703
| 'remove_payment_method';
@@ -3791,6 +3797,7 @@ export namespace VaultItemOperationResponse {
37913797
| '1pw_fill'
37923798
| '1pw_recover'
37933799
| '1pw_update_access_token'
3800+
| 'update_access_token'
37943801
| 'webmcp_invoke'
37953802
| 'add_payment_method'
37963803
| 'remove_payment_method';
@@ -3942,6 +3949,14 @@ export namespace WalletVaultItemSpec {
39423949
client: Authorization.KernelManagedOAuthClient | Authorization.CustomerManagedOAuthClient;
39433950

39443951
method: 'oauth';
3952+
3953+
/**
3954+
* Who refreshes an imported Link grant. kernel (default) means Kernel holds and
3955+
* rotates the refresh token. customer means your backend keeps the refresh token
3956+
* and replaces the access token with update_access_token; Kernel never refreshes
3957+
* or revokes the grant. Fixed at wallet creation.
3958+
*/
3959+
token_refresh?: 'kernel' | 'customer';
39453960
}
39463961

39473962
export namespace Authorization {
@@ -4268,6 +4283,7 @@ export type ItemPerformOperationParams =
42684283
| ItemPerformOperationParams.OnePasswordFillVaultItemOperationRequest
42694284
| ItemPerformOperationParams.OnePasswordRecoverVaultItemOperationRequest
42704285
| ItemPerformOperationParams.OnePasswordUpdateAccessTokenVaultItemOperationRequest
4286+
| ItemPerformOperationParams.UpdateAccessTokenVaultItemOperationRequest
42714287
| ItemPerformOperationParams.WebmcpInvokeVaultItemOperationRequest
42724288
| ItemPerformOperationParams.AddPaymentMethodVaultItemOperationRequest
42734289
| ItemPerformOperationParams.RemovePaymentMethodVaultItemOperationRequest;
@@ -4641,6 +4657,23 @@ export declare namespace ItemPerformOperationParams {
46414657
access_token_expires_at?: string;
46424658
}
46434659

4660+
export interface UpdateAccessTokenVaultItemOperationRequest {
4661+
/**
4662+
* Path param
4663+
*/
4664+
id_or_name: string;
4665+
4666+
/**
4667+
* Body param
4668+
*/
4669+
access_token: string;
4670+
4671+
/**
4672+
* Body param
4673+
*/
4674+
type: 'update_access_token';
4675+
}
4676+
46444677
export interface WebmcpInvokeVaultItemOperationRequest {
46454678
/**
46464679
* Path param
@@ -4794,40 +4827,57 @@ export declare namespace ItemUpsertParams {
47944827
* wallet with state.status=connected. An expired, invalid, revoked, or
47954828
* insufficiently scoped access token returns 400 and no wallet is created. Refresh
47964829
* expired tokens in your backend before importing them. A failed import does not
4797-
* modify existing wallets. After successful import, Kernel owns subsequent
4798-
* refresh-token rotation; the customer must stop refreshing this grant. Import
4799-
* does not verify the refresh token: if it or the configured client credentials
4800-
* are rejected during a later refresh, the imported wallet becomes degraded. An
4801-
* unknown refresh outcome also leaves it degraded; Kernel does not retry a refresh
4802-
* token that may already have been consumed. There is no in-place reauthorization
4803-
* operation for an imported wallet. If this imported wallet's credentials become
4804-
* unusable, obtain a fresh Link OAuth grant in your backend and create a wallet
4805-
* under a NEW wallet key. Use the new wallet for NEW cards and payments, not to
4806-
* retry an old payment whose outcome is uncertain. This does not replace the old
4807-
* grant, rebind existing cards, or resolve their payment outcomes. Retain the old
4808-
* wallet and its cards while reconciling any uncertain payments with the provider
4809-
* or support. Do not repeat an uncertain payment on the new wallet, and do not
4810-
* treat deletion as evidence that it did not execute. Deletion of the old wallet
4811-
* can remain blocked by unresolved child cards. Repeating a create for the same
4812-
* item key and non-secret spec returns the existing wallet without replacing
4813-
* tokens, even if they have rotated or the wallet needs reconnection. ID and name
4814-
* references resolving to the same config are equivalent. A different config or
4815-
* non-secret spec returns 409. This create operation does not replace an existing
4816-
* grant.
4830+
* modify existing wallets. By default (token_refresh=kernel), Kernel owns
4831+
* subsequent refresh-token rotation after a successful import; the customer must
4832+
* stop refreshing this grant. With token_refresh=customer, send only the access
4833+
* token: your backend keeps the refresh token and rotates the grant, and Kernel
4834+
* never refreshes or revokes it. Replace the stored access token with the wallet's
4835+
* update_access_token operation before each step that reaches Link, such as
4836+
* creating, authorizing or filling a card. When Link rejects the stored access
4837+
* token, operations return 409 without contacting Link again; update the token and
4838+
* retry. The remainder of this description applies to token_refresh=kernel. With
4839+
* token_refresh=kernel, Kernel owns subsequent refresh-token rotation; the
4840+
* customer must stop refreshing this grant. Import does not verify the refresh
4841+
* token: if it or the configured client credentials are rejected during a later
4842+
* refresh, the imported wallet becomes degraded. An unknown refresh outcome also
4843+
* leaves it degraded; Kernel does not retry a refresh token that may already have
4844+
* been consumed. There is no in-place reauthorization operation for an imported
4845+
* wallet. If this imported wallet's credentials become unusable, obtain a fresh
4846+
* Link OAuth grant in your backend and create a wallet under a NEW wallet key. Use
4847+
* the new wallet for NEW cards and payments, not to retry an old payment whose
4848+
* outcome is uncertain. This does not replace the old grant, rebind existing
4849+
* cards, or resolve their payment outcomes. Retain the old wallet and its cards
4850+
* while reconciling any uncertain payments with the provider or support. Do not
4851+
* repeat an uncertain payment on the new wallet, and do not treat deletion as
4852+
* evidence that it did not execute. Deletion of the old wallet can remain blocked
4853+
* by unresolved child cards. Repeating a create for the same item key and
4854+
* non-secret spec returns the existing wallet without replacing tokens, even if
4855+
* they have rotated or the wallet needs reconnection. ID and name references
4856+
* resolving to the same config are equivalent. A different config or non-secret
4857+
* spec returns 409. This create operation does not replace an existing grant.
48174858
*/
48184859
export interface ImportedLinkAuthorizationInput {
48194860
client: ImportedLinkAuthorizationInput.Client;
48204861

48214862
method: 'oauth';
48224863

48234864
/**
4824-
* Send the token pair from your backend. Both tokens must be from the same Link
4825-
* grant under the referenced client. Supply a currently valid access token. Kernel
4826-
* refreshes when needed after import and uses the expiry returned by Link for
4827-
* subsequent tokens. Tokens are never returned in wallet responses, events, or
4865+
* Send the tokens from your backend. Supply a currently valid access token. With
4866+
* token_refresh=kernel, also send the refresh token from the same Link grant under
4867+
* the referenced client; Kernel refreshes when needed after import and uses the
4868+
* expiry returned by Link for subsequent tokens. With token_refresh=customer, omit
4869+
* the refresh token. Tokens are never returned in wallet responses, events, or
48284870
* logs.
48294871
*/
48304872
tokens: ImportedLinkAuthorizationInput.Tokens;
4873+
4874+
/**
4875+
* Who refreshes an imported Link grant. kernel (default) means Kernel holds and
4876+
* rotates the refresh token. customer means your backend keeps the refresh token
4877+
* and replaces the access token with update_access_token; Kernel never refreshes
4878+
* or revokes the grant. Fixed at wallet creation.
4879+
*/
4880+
token_refresh?: 'kernel' | 'customer';
48314881
}
48324882

48334883
export namespace ImportedLinkAuthorizationInput {
@@ -4856,16 +4906,20 @@ export declare namespace ItemUpsertParams {
48564906
}
48574907

48584908
/**
4859-
* Send the token pair from your backend. Both tokens must be from the same Link
4860-
* grant under the referenced client. Supply a currently valid access token. Kernel
4861-
* refreshes when needed after import and uses the expiry returned by Link for
4862-
* subsequent tokens. Tokens are never returned in wallet responses, events, or
4909+
* Send the tokens from your backend. Supply a currently valid access token. With
4910+
* token_refresh=kernel, also send the refresh token from the same Link grant under
4911+
* the referenced client; Kernel refreshes when needed after import and uses the
4912+
* expiry returned by Link for subsequent tokens. With token_refresh=customer, omit
4913+
* the refresh token. Tokens are never returned in wallet responses, events, or
48634914
* logs.
48644915
*/
48654916
export interface Tokens {
48664917
access_token: string;
48674918

4868-
refresh_token: string;
4919+
/**
4920+
* Required with token_refresh=kernel; rejected with token_refresh=customer.
4921+
*/
4922+
refresh_token?: string;
48694923
}
48704924
}
48714925
}

0 commit comments

Comments
 (0)