# Hosted Widget Update  Mode

You can use Belvo's Hosted 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.


## Update Flow

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

1. You receive a link error from the API or a webhook.
2. You prompt your user inside your app to update their credentials or provide a new authentication token.
3. Once they initiate the update process, you make a server-side call to our `/api/token/` endpoint to generate an `access_token`, providing the user's `link_id`.

```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"
  }'
```
4. You then start the widget with the `access_token` you just generated. Because you provided 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 link is successfully updated, the Link is `valid` again and the `link_id` remains the same.

If the successfully updated Link is recurrent, we automatically trigger a historical update of the link, notifying you via webhook of any new data.

## 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?

Use the List all Links API request with the `status` query parameter set to `invalid` or `token_required` (see the example below). If any links are returned, those are the ones that need to be updated.


```curl Get all links needing to be updated
# 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
```