Hosted Widget Update Mode

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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

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?

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.

# 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