You can use the Connect widget to update a link that requires a new password or a new MFA token. You'll need to update a link if:

The institution requires a new MFA token to log in.
The password connected with the Link has been changed by the user.

Connect Widget update flow

The general flow of updating a link with the widget is:

You receive a link error.
You prompt inside your app for your user to update their credentials or provide a new authentication token. For example, by displaying an Update button for them to click.
Once they initiate the update process, you make a call from your server-side to generate an access_token, providing the user's link_id. See the code example below.

curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -d '{
    "id": "SECRET_ID",
    "password": "SECRET_PASSWORD",
    "link_id": "LINK_ID",
    "scopes": "read_institutions,write_links,read_links"
  }'

Start the widget and the user updates their link
Because you provide the link_id, we detect which kind of link update needs to be triggered (token or credentials) and guide the user through the process. Once they successfully provide their credentials or authentication token, we set the status of the link to valid.

✳️ Done! Once a recurrent link is successfully updated, the link status is valid again and the link_id remains the same. You’ll receive a Success callback response in the widget.

If the successfully updated link is a recurrent one, we automatically trigger an update of the link. If we find fresh data, you’ll receive historical update webhooks.

❗️
What happens if there is an error when updating the link?
You’ll keep receiving success and error callbacks in the widget as usual. The
Link status won’t be valid again until it’s been successfully updated.

How do I know if a link needs to be updated?

A link will need to be updated in the following scenarios:

Scenario 1: you receive an error from the API
When doing a POST call to our API, you can receive errors meaning that the link needs to be updated:

Response	Error code	Reason
400	`invalid_link`	The link has been invalidated due to several login errors.
428	`token_required`	An MFA token is required by the institution to login.

Scenario 2: you receive a webhook error for a recurrent link
During the daily refresh of your recurrent links, we will send an event in case one of your links needs to be updated to be refreshed.

Event	Reason
`invalid_credentials`	Every time we cannot refresh a recurrent link because of invalid credentials.
`token_required`	Whenever we need a new MFA token to refresh the recurrent link.

How can I know which links need to be updated?

Using link listing and checking the link status, you can see which links need to be updated by your users.
If the link status is invalid or token_required, it needs to be updated.

For example:

# invalid links
curl -u Secret-Key-ID:Secret-Key-PASSWORD  \
https://sandbox.belvo.com/api/links/?status=invalid

# token required links
curl -u Secret-Key-ID:Secret-Key-PASSWORD  \
https://sandbox.belvo.com/api/links/?status=token_required

curl -u [Secret Key ID]:[Secret Key PASSWORD]  \
https://sandbox.belvo.com/api/links/[LINK ID]/

curl -u [Secret Key ID]:[Secret Key PASSWORD]  \
https://sandbox.belvo.com/api/links/

How can I test the widget in update mode?

Use the Heimdall institution in our sandbox environment. After you register a link with the institution, any additional POST calls made to the institution will return a 428 Token Required response, where the status of the link will be changed to token_required.

Then all you need to do is pass the link_id when you start the widget, and when you successfully provide the necessary credentials, the link status will be updated to valid again.