Updating Items via Link

Use Link's update mode to fix Items that require re-authentication and resolve the ITEM_LOGIN_REQUIRED error code

When to use update mode

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.

Using update mode

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:

 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// 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.

 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// 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.

If your integration is still using a public_token to open Link in update mode, see the migration guide to upgrade to link_tokens. You can also see the maintenance guide to troubleshoot any public_token issues.

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.

Testing update mode

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.

Related errors

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.