Updating Items via Plaid Link

Occasionally, an Item will need to have authentication information updated. When this happens, the Item will go into an error state. A common cause for this is if your user updates their credentials with their institution.

You will be notified when an Item goes into error state via a webhook (recommended) or an error response to an API request. When this happens, we recommend you notify your user via an email or push notification and request that they enter your application to update their authentication details. Within your application, launching Plaid Link in update mode will allow your user to re-authenticate with Plaid. 

Item error webhook sent to your application

The recommended way to getting notified of an Item going into an error state is via webhooks. We will notify you that an Item's authentication information needs to be updated via an Item ERROR webhook. Here's an example of a webhook that is fired when your user's credentials are no longer valid:

{
  "webhook_type": "ITEM",
  "webhook_code": "ERROR",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": {
    "display_message": "The provided credentials were not correct. 
Please try again.",
    "error_code": "ITEM_LOGIN_REQUIRED",
    "error_message": "the provided credentials were not correct",
    "error_type": "ITEM_ERROR",
    "status": 400
  }
}

You make a request to create a public_token

Next, you will need to generate a new public_token for the Item. This can be done by making a request to the /item/public_token/create endpoint and specifying the relevant access_token associated with the Item.

Plaid returns a newly created public_token

In response to your request to create to the /item/public_token/create endpoint, we will return a new public_token for the Item. As a reminder, public_tokens will expire after 30 minutes. 

Initialize Plaid Link in your app with the newly created public_token

Now that you have generated a public_token for the Item, you can launch Plaid Link in update mode and specify the new public_token in the token field. When you initialize Plaid Link in update mode, Plaid Link will immediately launch on the credentials pane for the institution associated with the Item.

User re-authenticates with Plaid

Within the Plaid Link pane, your user will provide their updated credentials and any MFA required, and we will verify these updated authentication details. 

onSuccess callback indicates that the user successfully re-authenticated

To let you know that your user's Item has successfully re-authenticated, we will fire an onSuccess callback. This callback will be identical to the onSuccess callback that is fired upon initial Item creation. The only difference here is that there is no need to performa any additional token exchange step since the Item's access_token does not change in this process. 

Additional technical details on this flow can be found in our API docs here.