Updating Items via Link

Over time, Items may need to refresh authentication information. This can happen if the user changes a password, if MFA requirements change, or if the login becomes locked. An Item can also require its authentication to be refreshed if it was only authorized for a limited amount of time and the authorization has expired or is about to expire, which can happen to Items from institutions that use OAuth-based Link flows.

Receiving an ITEM_LOGIN_REQUIRED error or a PENDING_EXPIRATION webhook indicates that the Item should be re-initialized via update mode. You will need to tell your user to return to your app to fix their Item, such as via in-app messaging and/or email or text.

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 should be specified when creating a link_token for update mode. You can obtain a link_token using the /link/token/create endpoint:

// Create a one-time use link_token for the Item.
// This link_token can be used to initialize Link
// in update mode for the user
app.post('/create_link_token', async (request, response, next) => {
  const linkTokenResponse = await client.createLinkToken({
    user: {
      client_user_id: 'UNIQUE_USER_ID',
    },
    client_name: 'Your App Name Here',
    country_codes: ['US'],
    language: 'en',
    webhook: 'https://webhook.sample.com',
    access_token: 'ENTER_YOUR_ACCESS_TOKEN_HERE',
  });
  // Use the link_token to initialize Link
  response.json({ link_token: linkTokenResponse.link_token });
});

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.

// Initialize Link with the token parameter
// set to the generated link_token for the Item
const linkHandler = Plaid.create({
  token: 'GENERATED_LINK_TOKEN',
  onSuccess: (public_token, metadata) => {
    // You do not need to repeat the /item/public_token/exchange
    // process when a user uses Link in update mode.
    // The Item's access_token has not changed.
  },
  onExit: (err, metadata) => {
    // The user exited the Link flow.
    if (err != null) {
      // The user encountered a Plaid API error prior
      // to exiting.
    }
    // metadata contains the most recent API request ID and the
    // Link session ID. Storing this information is helpful
    // for support.
  },
});

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.

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.

Below is a list of errors that you may encounter in update mode or that may cause you to launch the update mode flow:

• ITEM_LOGIN_REQUIRED – The financial institution indicated that the user's password or MFA information has changed. They will need to reauthenticate via Link's update mode.
• ITEM_NO_ERROR – Link was initialized in update mode for an Item that is in a good state. No further action is required.
• INVALID_UPDATED_USERNAME – The username associated with an item is no longer valid.