This articles refers to the multi-region widget
The content of this article refers to the multi-region widget (applicable for Mexico). If you wish to operate in Brazil, please see our Connect Widget for Regulated OFDA.

You can use Belvo's 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 user has changed the password connected with the Link.


br
# Connect Widget update flow

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

1. You receive a link error.
2. 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.
3. 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
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"
  }'
```

1. 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 List all Links 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:


```curl
# 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
curl -u SECRET_ID:SECRET_PASSWORD  \
https://sandbox.belvo.com/api/links/[LINK ID]/
```


```curl
curl -u SECRET_ID:SECRET_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.