Updating Items via Link

Update mode is used to update authentication or authorization for an Item. The most common reason for this is when access to an existing Item stops working: if the end user changes a password, if multi-factor authentication (MFA) requirements change, or if the login becomes locked. An Item can also require its authentication to be refreshed with update mode if it was only authorized for a limited amount of time and the authorization has expired or is nearing expiration, which can happen to Items from institutions that use OAuth flows in Plaid Link.

Update mode can also be used to request permission to access data that the user did not originally grant during the initial link flow. This can include specific OAuth permissions, or access to new accounts or additional product scopes. Update mode can be used to manage permissions granted via OAuth, as well as permissions granted directly through Plaid via Account Select or the opt-in Data Transparency Messaging beta.

Receiving an ITEM_LOGIN_REQUIRED error or a PENDING_EXPIRATION webhook indicates that the Item should be re-initialized via update mode.

If you receive the ITEM_LOGIN_REQUIRED error after calling a Plaid endpoint, implement Link in update mode during the user flow, and ask the user to re-authenticate before proceeding to the next step in your flow.

If you receive the ITEM_LOGIN_REQUIRED error via the ITEM: ERROR webhook, or if you receive the PENDING_EXPIRATION webhook, re-authenticate with Link in update mode when the user is next in your app. You will need to tell your user (using in-app messaging and/or notifications such as email or text message) to return to your app to fix their Item.

When resolving these errors, for most institutions, Plaid will present an abbreviated re-authentication flow requesting only the minimum user input required to repair the Item. For example, if the Item entered an error state because the user's OTP token expired, the user may be prompted to provide another OTP token, but not to fully re-login to the institution.

You can use update mode to request your users to share new accounts with you. Receiving a NEW_ACCOUNTS_AVAILABLE webhook indicates that Plaid has detected new accounts that you may want to ask your users to share. For more details, see Using update mode to request new accounts.

In most cases, it is not necessary to use update mode to add a product to an existing Item. Instead, you can simply call the products's endpoints, and it will be automatically added to the Item. You will need to use update mode to add products in the following situations: if you are adding Assets or Income, if you are using Data Transparency Messaging, or if you receive an ACCESS_NOT_GRANTED or NO_AUTH_ACCOUNTS error after attempting to add Identity or Auth to an Item.

For more details, see Using update mode to request additional products.

Triggering update mode for an OAuth institution will cause the user to re-enter the OAuth flow. They can then grant any required OAuth permissions they failed to grant originally, or restore OAuth permissions they may have revoked. The update mode flow for OAuth institutions will also contain guidance recommending which permissions the user should grant: for more details, see the OAuth documentation.

To use update mode for an Item, initialize Link with a link_token configured with the access_token for the Item that you wish to update. Note that no products or product-specific request parameters should be specified when creating a link_token for update mode, unless you are using update mode to add Assets or Income, or if you are using Auth and/or Identity and wish to use the beta Update Mode with Product Validations flow. You can obtain a link_token using the /link/token/create endpoint.

If your integration uses redirect URIs normally, create the Link token with a redirect URI, as described in Configure your Link token with your redirect URI.

1// Create a one-time use link_token for the Item.
2// This link_token can be used to initialize Link
3// in update mode for the user
4const configs = {
5  user: {
6    client_user_id: 'UNIQUE_USER_ID',
7  },
8  client_name: 'Your App Name Here',
9  country_codes: [CountryCode.Us],
10  language: 'en',
11  webhook: 'https://webhook.sample.com',
12  redirect_uri: "https://www.sample.com/redirect.html",
13  access_token: 'ENTER_YOUR_ACCESS_TOKEN_HERE',
14};
15app.post('/create_link_token', async (request, response, next) => {
16  const linkTokenResponse = await client.linkTokenCreate(configs);
17
18  // Use the link_token to initialize Link
19  response.json({ link_token: linkTokenResponse.data.link_token });
20});

Link auto-detects the appropriate institution and handles the credential and multi-factor authentication process, if needed.

An Item's access_token does not change when using Link in update mode, so there is no need to repeat the exchange token process.

1// Initialize Link with the token parameter
2// set to the generated link_token for the Item
3const linkHandler = Plaid.create({
4  token: 'GENERATED_LINK_TOKEN',
5  onSuccess: (public_token, metadata) => {
6    // You do not need to repeat the /item/public_token/exchange
7    // process when a user uses Link in update mode.
8    // The Item's access_token has not changed.
9  },
10  onExit: (err, metadata) => {
11    // The user exited the Link flow.
12    if (err != null) {
13      // The user encountered a Plaid API error prior
14      // to exiting.
15    }
16    // metadata contains the most recent API request ID and the
17    // Link session ID. Storing this information is helpful
18    // for support.
19  },
20});

Link will automatically detect the institution ID associated with the link_token and present the appropriate credential view to your user.

When an Item is restored from the ITEM_LOGIN_REQUIRED state via update mode, if it has been initialized with a product that sends Item webhooks (such as Transactions or Investments), the next webhook fired for the Item will include data for all missed information back to the last time Plaid made a successful connection to the Item.

You can allow end users to add new accounts to an Item by enabling Account Select when initializing Link in update mode. To do so, first initialize Link for update mode by creating a link_token using the /link/token/create endpoint, passing in the access_token and other parameters as you normally would in update mode.

In addition, make sure you specify the following:

1. The update.account_selection_enabled flag set to true. If this flag is not available to you, make sure to update your client library to the latest version.

2. (Optional) A link_customization_name. The settings on this customization will determine which View Behavior for the Account Select pane is shown in the update mode flow.

3. (Optional) Any account_filters to specify account filtering. Note that this field can only be set for update mode if update.account_selection_enabled is set to true.

Once your user has updated their account selection, all selected accounts will be shared in the accounts field in the onSuccess() callback from Link. Any de-selected accounts will no longer be shared with you. You will only be able to receive data for these accounts the user selects in update mode going forward.

Adding an account through update mode will cause Plaid to fetch data for the newly added account. However, recurring transactions streams will not be calculated for the new account until either the next periodic transactions update for the Item occurs or the /transactions/refresh endpoint is called.

This update mode flow can also be used to remove accounts from an Item. We recommend that you remove any data associated with accounts that your user has de-selected. Note that Chase is an exception to the ability to remove accounts via update mode; to remove access to a specific account on a Chase Item, the end user must do so through the online Chase Security Center.

1curl -X POST https://sandbox.plaid.com/link/token/create \
2-H 'Content-Type: application/json' \
3-d '{
4  "client_id": "${PLAID_CLIENT_ID}",
5  "secret": "${PLAID_SECRET}",
6  "client_name": "My App",
7  "user": { "client_user_id": "${UNIQUE_USER_ID}" },
8  "country_codes": ["US"],
9  "language": "en",
10  "webhook": "https://webhook.sample.com",
11  "access_token": "${ACCESS_TOKEN}",
12  "link_customization_name": "account_selection_v2_customization",
13  "redirect_uri": "https://www.sample.com/redirect.html",
14  "update": { "account_selection_enabled": true }
15}'

When using the Assets product specifically, if a user selects additional accounts during update mode but does not successfully complete the Link flow, Assets authorization will be revoked from the Item. If this occurs, have the user go through a new Link flow in order to generate an Asset Report, or, if you have Data Transparency Messaging enabled, use update mode to re-authorize the Item for assets, as described in the next section.

If you are using update mode to add a debitable checking or savings account in response to a NO_AUTH_ACCOUNTS error, see Resolving ACCESS_NOT_GRANTED or NO_AUTH_ACCOUNTS errors via product validations for a better method to resolve this error.

You will need to use update mode to add products in the following situations: if you are adding Assets or Income, if you receive an ACCESS_NOT_GRANTED or NO_AUTH_ACCOUNTS error after attempting to add Identity or Auth to an Item, or if you are using Data Transparency Messaging. Otherwise, you can simply call the product's endpoint to add it; for more details, see Adding products post-Link.

Adding Assets or Bank Income

Because Assets and Income may be used for underwriting use cases, they have unique consent flows in Link. To add Assets or Income to an Item that did not previously have those products enabled, you will need to send the user through update mode so that they can go through the product-specific consent flow before Assets or Income is added to the Item.

The process to do this is the same as described in Using update mode, except that you will also include the products array in the request with the value assets or income for the product you wish to add.

If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the consent panes. Otherwise, they will be prompted to complete the full flow.

The Auth and Identity products can be added to an Item post-Link, by calling an Auth or Identity related endpoint, rather than including auth or identity in the products array. However, if the user did not share the necessary permissions or accounts to support these products, the Item will return an ACCESS_NOT_GRANTED or NO_AUTH_ACCOUNTS error. Update Mode with Product Validations (UMPV) applies product-specific validations to the selections a user makes in the update mode flow, resulting in higher conversion than resolving these errors via regular update mode.

The process to use UMPV is the same as described in Using update mode, except that you will also include the products array in the request with the value auth and/or identity for the product(s) you wish to validate.

UMPV will enforce the same level of product validation as is normally used on an initial Link attempt: the user will be instructed on which permissions to grant, and if they do not make these selections, they will be prompted to go back through the flow. In the case of NO_AUTH_ACCOUNTS, the account selection flow will also be automatically enabled if necessary.

UMPV can also be used preventatively, to prevent users in the update mode flow from accidentally removing permissions they have already granted. Applying UMPV to any update mode session for an Auth- or Identity-enabled Item will prompt users to fix their selections if they remove the accounts or permissions required for these products.

UMPV can only be used for auth or identity. It is also not compatible with Adding Assets or Bank Income; the two cannot be used in a single update mode flow, although they can be used on the same Item, via separate update mode sessions.

Requesting additional consented products for Data Transparency Messaging

If you have Data Transparency Messaging enabled, you need user consent to access new products. To do so, first initialize Link for update mode by creating a link_token using the /link/token/create endpoint. For OAuth institutions, ensure you configure the Link token with a redirect URI, as described in Configure your Link token with your redirect URI.

In addition, make sure you specify the following:

• The additional_consented_products field should be set to include any new products you want to gather consent for.
  • For example, if Link was initialized with just Transactions and you want to upgrade to Identity, you would pass in identity to the additional_consented_products field.
  • To see the currently authorized and consented products on an Item, use the /item/get endpoint.
• The link_customization_name should be set to a customization with Data Transparency Messaging enabled. The use case string should also be broadened to include your reasons for accessing the new data. If the use case is not customized, the default use case will be present on the Data Transparency Messaging pane.

If the upgrade was successful, you will receive the onSuccess() callback and you will have access to the API endpoints for all of the products you passed into Link update mode. The new products will only be billed once the related API endpoints are called, even if they would otherwise be billed upon Item initialization (e.g., Transactions).

Update mode can be tested in the Sandbox using the /sandbox/item/reset_login endpoint, which will force a given Item into an ITEM_LOGIN_REQUIRED state.

For a real-life example that illustrates the handling of update mode, see linkTokens.js and LaunchLink.tsx. These files contain the Link update mode code for the React-based Plaid Pattern sample app.

To demonstrate the user experience of various update mode flows, below are screenshots of update mode that correspond to different Account Select V2 settings.