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.