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:

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 -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"
  }'

# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from belvo.client import Client

client = Client("my-secret-key-id", "my-secret-key-password",  "https://sandbox.belvo.com")

token = client.WidgetToken.create(link="user-link-id") # Adding the link_id.

# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

client = Belvo::Client.new(
  "my-secret-key-id", 
  "my-secret-key-password",
  "https://sandbox.belvo.com"
)

client.widget_token.create(options: {link: "user-link-id"}) # Adding the link_id.

// check our node package on github
// https://github.com/belvo-finance/belvo-js
var belvo = require('belvo').default;

var client = new belvo(
  'my-secret-key-id',
  'my-secret-key-password',
  'https://sandbox.belvo.com'
);

client.connect()
  .then(function () {
        client.widgetToken.create({ link: 'user-link-id' }) // Adding the link_id.
      .then((response) => {
      res.json(response);
        })
      .catch((error) => {
      res.status(500).send({
        message: error.message
      });
    });
});

4. 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:

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.

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.