curl --request POST \
  --url https://api.prod.finverse.net/login_identity/refresh \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "link_customizations": {
    "redirect_uri": "{{REDIRECT_URI}}",
    "state": "{{customer_app_id}}_stateparameter",
    "ui_mode": "redirect"
  },
  "user_present": true
}
'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3dC9jcnlwdG9LZXlzL2p3dC1rZXkvY3J5cHRvS2V5VmVyc2lvbnMvMSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2FwaS5wcm9kLmZpbnZlcnNlLm5ldCIsImNsaWVudElkIjoiMDFGNzMwWTIyTTdKSERZQjRFNEsxREsyV0ciLCJjdXN0b21lckFwcElkIjoiMDFGNzMwWTI0NjlDMzdHM0RCNTNHUFRYOTkiLCJleHAiOjE3MjcwNjYyNzYsImlhdCI6MTcyNzA2NTk3NiwiaW5zdGl0dXRpb25JZCI6InRlc3RiYW5rMiIsImlzcyI6ImZpbnZlcnNlLXByb2QiLCJsaW5rVG9rZW5SZXF1ZXN0Ijoie1wicmVkaXJlY3RfdXJpXCI6XCJodHRwczovL2VucTRhNjBqbjN6dXAueC5waXBlZHJlYW0ubmV0L2NhbGxiYWNrXCIsXCJzdGF0ZVwiOlwiMDFGNzMwWTI0NjlDMzdHM0RCNTNHUFRYOTlfc3RhdGVwYXJhbWV0ZXJcIixcInVpX21vZGVcIjpcInJlZGlyZWN0XCJ9IiwibG9naW5JZGVudGl0eUlkIjoiMDFKOEVKN1owQ0ZKVFdUS0U0Vlk5N0pENEciLCJwcm9kdWN0RmxvdyI6IlJFRlJFU0hfREFUQV9SRVRSSUVWQUwiLCJyZWRpcmVjdFVyaSI6Imh0dHBzOi8vZW5xNGE2MGpuM3p1cC54LnBpcGVkcmVhbS5uZXQvY2FsbGJhY2siLCJzY29wZSI6ImN1c3RvbWl6YXRpb246Z2V0IGluc3RpdHV0aW9uIGZ2TGlua1N0YXR1czpyZWFkIGxpbmtBcGk6dXBkYXRlIiwic3ViIjoiMDFGNzMwWTIyTTdKSERZQjRFNEsxREsyV0cifQ.T_RA97CZ0KRBHyX1sMIhpQX_NLWMaYKz2i3227yY_NKJ4uWYZ5SESqquwsGZITqCO-LlYMVwZNvJ3r2F-JlmKCs5-trtEiuTkNYN_dlgv8u8knY6YTsDHWegYwqZcR0DdTYZLeowbOpfsXzOTExXQaaowY3VWCQ78IWXo5fISy0LqZ4V-GMKs5un4V4CLKgYzWPOGaD-YDDrlSaFtOB-fSlymPaeOJ4nzRlsJr84IGII80NcC_3Z_A3qx5kru30pv4PDuXA5GcbUG_5FYFbWs4rRhhpNPcVa5wE8BlHZ4OF6QZimrd7zSo6mzIS9YuWA1OuXLK6aPiQnzEu-Bo-TT0jSMZCWOzOVc7sgLotjxMFMdUMo2DUQxLiiP-AzeyPjQFHae-uyY4OYkf5Ydsta46-Zr2GPeU1kpEo2hsSuYKfnmoq7VhfVUcyanvab6NqtJyBj5oCeYofSAHNAAJMwtV3hgpEWAuNaEm-45oDdyuhWHHreBGjjrKHAMnBVHolfnrHqK92becuGSpadeTpsmim2XDVijm4V0dRHKHrqDQYt2WWjR6GMBUqtaKJt0FrR-rZtzlNEiHTjIYzau1EsqY3Lso4dsf5DXjk8TDBzOwjAN4ZZd54DPRBbXAeS20ok3thDC2ljquIOOcsKjBRITQUdI-ooY7_dWVY7bm76FlU",
  "expires_in": 300,
  "issued_at": "2024-09-23T04:32:56.000Z",
  "link_url": "https://link.prod.finverse.net/onboarding/refresh?token=eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3dC9jcnlwdG9LZXlzL2p3dC1rZXkvY3J5cHRvS2V5VmVyc2lvbnMvMSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2FwaS5wcm9kLmZpbnZlcnNlLm5ldCIsImNsaWVudElkIjoiMDFGNzMwWTIyTTdKSERZQjRFNEsxREsyV0ciLCJjdXN0b21lckFwcElkIjoiMDFGNzMwWTI0NjlDMzdHM0RCNTNHUFRYOTkiLCJleHAiOjE3MjcwNjYyNzYsImlhdCI6MTcyNzA2NTk3NiwiaW5zdGl0dXRpb25JZCI6InRlc3RiYW5rMiIsImlzcyI6ImZpbnZlcnNlLXByb2QiLCJsaW5rVG9rZW5SZXF1ZXN0Ijoie1wicmVkaXJlY3RfdXJpXCI6XCJodHRwczovL2VucTRhNjBqbjN6dXAueC5waXBlZHJlYW0ubmV0L2NhbGxiYWNrXCIsXCJzdGF0ZVwiOlwiMDFGNzMwWTI0NjlDMzdHM0RCNTNHUFRYOTlfc3RhdGVwYXJhbWV0ZXJcIixcInVpX21vZGVcIjpcInJlZGlyZWN0XCJ9IiwibG9naW5JZGVudGl0eUlkIjoiMDFKOEVKN1owQ0ZKVFdUS0U0Vlk5N0pENEciLCJwcm9kdWN0RmxvdyI6IlJFRlJFU0hfREFUQV9SRVRSSUVWQUwiLCJyZWRpcmVjdFVyaSI6Imh0dHBzOi8vZW5xNGE2MGpuM3p1cC54LnBpcGVkcmVhbS5uZXQvY2FsbGJhY2siLCJzY29wZSI6ImN1c3RvbWl6YXRpb246Z2V0IGluc3RpdHV0aW9uIGZ2TGlua1N0YXR1czpyZWFkIGxpbmtBcGk6dXBkYXRlIiwic3ViIjoiMDFGNzMwWTIyTTdKSERZQjRFNEsxREsyV0cifQ.T_RA97CZ0KRBHyX1sMIhpQX_NLWMaYKz2i3227yY_NKJ4uWYZ5SESqquwsGZITqCO-LlYMVwZNvJ3r2F-JlmKCs5-trtEiuTkNYN_dlgv8u8knY6YTsDHWegYwqZcR0DdTYZLeowbOpfsXzOTExXQaaowY3VWCQ78IWXo5fISy0LqZ4V-GMKs5un4V4CLKgYzWPOGaD-YDDrlSaFtOB-fSlymPaeOJ4nzRlsJr84IGII80NcC_3Z_A3qx5kru30pv4PDuXA5GcbUG_5FYFbWs4rRhhpNPcVa5wE8BlHZ4OF6QZimrd7zSo6mzIS9YuWA1OuXLK6aPiQnzEu-Bo-TT0jSMZCWOzOVc7sgLotjxMFMdUMo2DUQxLiiP-AzeyPjQFHae-uyY4OYkf5Ydsta46-Zr2GPeU1kpEo2hsSuYKfnmoq7VhfVUcyanvab6NqtJyBj5oCeYofSAHNAAJMwtV3hgpEWAuNaEm-45oDdyuhWHHreBGjjrKHAMnBVHolfnrHqK92becuGSpadeTpsmim2XDVijm4V0dRHKHrqDQYt2WWjR6GMBUqtaKJt0FrR-rZtzlNEiHTjIYzau1EsqY3Lso4dsf5DXjk8TDBzOwjAN4ZZd54DPRBbXAeS20ok3thDC2ljquIOOcsKjBRITQUdI-ooY7_dWVY7bm76FlU&ui_mode=redirect",
  "login_identity_id": "01J8EJ7Z0CFJTWTKE4VY97JD4G",
  "token_type": "Bearer"
}

login_identity/refresh (User-present data refresh)

Trigger a data refresh request for a Login Identity, requesting Finverse to start authenticating with the institution (using stored credentials), and if authentication succeeds, to fetch new data for the Login Identity.

This refresh request example uses the user-present mode see the next request for an example of the background refresh mode.

Note: a success response only indicates that the refresh request has been accepted and is being processed. Authentication or data retrieval may still fail asynchronously (e.g. a user may have changed their credentials).

Authorization: login_identity_token

Refresh requirements

When a refresh is requested, Finverse will first check that the refresh is allowed:

All data refreshes: Finverse first checks whether the Login Identity is eligible for refreshes, i.e. the Login Identity has refresh.refresh_allowed = true (see GET /login_identity). This means:
- The user’s credentials are available (i.e. the user provided consent to store the credentials for refreshes); and
- The user’s Login Identity is in refreshable state (e.g. previous linking/refresh attempts did not result in a persistent user-error).
Background data refreshes: Finverse also checks whether the institution being refreshed is generally available for background refreshes, i.e. the institution has login_details.refresh_supported = true. (see GET /institutions).

If the refresh is allowed, Finverse will start re-authenticating the Login Identity with the institution, and if authentication succeeds, Finverse will then fetch new data for the Login Identity.

link_customizations (object, optional)

Optional parameters to customize the behaviour of Finverse Link’s UI to fit your implementation requirements.

Monitoring refresh status

To check the authentication & data retrieval progress: see the section on “Monitoring refresh status” under “Data Refresh” above.

Token handling

Note: only applies if using GET /link/fvlink/status/{login_identity_id} to check the refresh result.

Usage: link_token can be used by either back-end or front-end clients to check the linking status via GET /link/fvlink/status/{login_identity_id}. It is the only Finverse API token that is allowed for use by front-end clients.

Renewal: link_token expires after 5 minutes. Repeat the refresh request if the token has expired.

Link URL handling

Note: only applies to user-present refresh mode (i.e. where user_present = true).

Depending on your preferred refresh UI, if the user is present, you can initiate a refresh and then either:

Immediately open the Link URL, so the user can see the refresh status & handle any 2FA action steps;
(recommended) Store the link_url and monitor the refresh status in the background until the refresh status is updated, and then either:
1. If a 2FA action is required, open the link_url so the user can complete the action steps using the Finverse Link UI.
2. If the refresh is successful or encounters an error, either directly display the refresh result to your user in your application, or open the link_url for the Finverse Link UI to display a success/error message to the user.

POST

login_identity

refresh

curl --request POST \
  --url https://api.prod.finverse.net/login_identity/refresh \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "link_customizations": {
    "redirect_uri": "{{REDIRECT_URI}}",
    "state": "{{customer_app_id}}_stateparameter",
    "ui_mode": "redirect"
  },
  "user_present": true
}
'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3dC9jcnlwdG9LZXlzL2p3dC1rZXkvY3J5cHRvS2V5VmVyc2lvbnMvMSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2FwaS5wcm9kLmZpbnZlcnNlLm5ldCIsImNsaWVudElkIjoiMDFGNzMwWTIyTTdKSERZQjRFNEsxREsyV0ciLCJjdXN0b21lckFwcElkIjoiMDFGNzMwWTI0NjlDMzdHM0RCNTNHUFRYOTkiLCJleHAiOjE3MjcwNjYyNzYsImlhdCI6MTcyNzA2NTk3NiwiaW5zdGl0dXRpb25JZCI6InRlc3RiYW5rMiIsImlzcyI6ImZpbnZlcnNlLXByb2QiLCJsaW5rVG9rZW5SZXF1ZXN0Ijoie1wicmVkaXJlY3RfdXJpXCI6XCJodHRwczovL2VucTRhNjBqbjN6dXAueC5waXBlZHJlYW0ubmV0L2NhbGxiYWNrXCIsXCJzdGF0ZVwiOlwiMDFGNzMwWTI0NjlDMzdHM0RCNTNHUFRYOTlfc3RhdGVwYXJhbWV0ZXJcIixcInVpX21vZGVcIjpcInJlZGlyZWN0XCJ9IiwibG9naW5JZGVudGl0eUlkIjoiMDFKOEVKN1owQ0ZKVFdUS0U0Vlk5N0pENEciLCJwcm9kdWN0RmxvdyI6IlJFRlJFU0hfREFUQV9SRVRSSUVWQUwiLCJyZWRpcmVjdFVyaSI6Imh0dHBzOi8vZW5xNGE2MGpuM3p1cC54LnBpcGVkcmVhbS5uZXQvY2FsbGJhY2siLCJzY29wZSI6ImN1c3RvbWl6YXRpb246Z2V0IGluc3RpdHV0aW9uIGZ2TGlua1N0YXR1czpyZWFkIGxpbmtBcGk6dXBkYXRlIiwic3ViIjoiMDFGNzMwWTIyTTdKSERZQjRFNEsxREsyV0cifQ.T_RA97CZ0KRBHyX1sMIhpQX_NLWMaYKz2i3227yY_NKJ4uWYZ5SESqquwsGZITqCO-LlYMVwZNvJ3r2F-JlmKCs5-trtEiuTkNYN_dlgv8u8knY6YTsDHWegYwqZcR0DdTYZLeowbOpfsXzOTExXQaaowY3VWCQ78IWXo5fISy0LqZ4V-GMKs5un4V4CLKgYzWPOGaD-YDDrlSaFtOB-fSlymPaeOJ4nzRlsJr84IGII80NcC_3Z_A3qx5kru30pv4PDuXA5GcbUG_5FYFbWs4rRhhpNPcVa5wE8BlHZ4OF6QZimrd7zSo6mzIS9YuWA1OuXLK6aPiQnzEu-Bo-TT0jSMZCWOzOVc7sgLotjxMFMdUMo2DUQxLiiP-AzeyPjQFHae-uyY4OYkf5Ydsta46-Zr2GPeU1kpEo2hsSuYKfnmoq7VhfVUcyanvab6NqtJyBj5oCeYofSAHNAAJMwtV3hgpEWAuNaEm-45oDdyuhWHHreBGjjrKHAMnBVHolfnrHqK92becuGSpadeTpsmim2XDVijm4V0dRHKHrqDQYt2WWjR6GMBUqtaKJt0FrR-rZtzlNEiHTjIYzau1EsqY3Lso4dsf5DXjk8TDBzOwjAN4ZZd54DPRBbXAeS20ok3thDC2ljquIOOcsKjBRITQUdI-ooY7_dWVY7bm76FlU",
  "expires_in": 300,
  "issued_at": "2024-09-23T04:32:56.000Z",
  "link_url": "https://link.prod.finverse.net/onboarding/refresh?token=eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3dC9jcnlwdG9LZXlzL2p3dC1rZXkvY3J5cHRvS2V5VmVyc2lvbnMvMSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2FwaS5wcm9kLmZpbnZlcnNlLm5ldCIsImNsaWVudElkIjoiMDFGNzMwWTIyTTdKSERZQjRFNEsxREsyV0ciLCJjdXN0b21lckFwcElkIjoiMDFGNzMwWTI0NjlDMzdHM0RCNTNHUFRYOTkiLCJleHAiOjE3MjcwNjYyNzYsImlhdCI6MTcyNzA2NTk3NiwiaW5zdGl0dXRpb25JZCI6InRlc3RiYW5rMiIsImlzcyI6ImZpbnZlcnNlLXByb2QiLCJsaW5rVG9rZW5SZXF1ZXN0Ijoie1wicmVkaXJlY3RfdXJpXCI6XCJodHRwczovL2VucTRhNjBqbjN6dXAueC5waXBlZHJlYW0ubmV0L2NhbGxiYWNrXCIsXCJzdGF0ZVwiOlwiMDFGNzMwWTI0NjlDMzdHM0RCNTNHUFRYOTlfc3RhdGVwYXJhbWV0ZXJcIixcInVpX21vZGVcIjpcInJlZGlyZWN0XCJ9IiwibG9naW5JZGVudGl0eUlkIjoiMDFKOEVKN1owQ0ZKVFdUS0U0Vlk5N0pENEciLCJwcm9kdWN0RmxvdyI6IlJFRlJFU0hfREFUQV9SRVRSSUVWQUwiLCJyZWRpcmVjdFVyaSI6Imh0dHBzOi8vZW5xNGE2MGpuM3p1cC54LnBpcGVkcmVhbS5uZXQvY2FsbGJhY2siLCJzY29wZSI6ImN1c3RvbWl6YXRpb246Z2V0IGluc3RpdHV0aW9uIGZ2TGlua1N0YXR1czpyZWFkIGxpbmtBcGk6dXBkYXRlIiwic3ViIjoiMDFGNzMwWTIyTTdKSERZQjRFNEsxREsyV0cifQ.T_RA97CZ0KRBHyX1sMIhpQX_NLWMaYKz2i3227yY_NKJ4uWYZ5SESqquwsGZITqCO-LlYMVwZNvJ3r2F-JlmKCs5-trtEiuTkNYN_dlgv8u8knY6YTsDHWegYwqZcR0DdTYZLeowbOpfsXzOTExXQaaowY3VWCQ78IWXo5fISy0LqZ4V-GMKs5un4V4CLKgYzWPOGaD-YDDrlSaFtOB-fSlymPaeOJ4nzRlsJr84IGII80NcC_3Z_A3qx5kru30pv4PDuXA5GcbUG_5FYFbWs4rRhhpNPcVa5wE8BlHZ4OF6QZimrd7zSo6mzIS9YuWA1OuXLK6aPiQnzEu-Bo-TT0jSMZCWOzOVc7sgLotjxMFMdUMo2DUQxLiiP-AzeyPjQFHae-uyY4OYkf5Ydsta46-Zr2GPeU1kpEo2hsSuYKfnmoq7VhfVUcyanvab6NqtJyBj5oCeYofSAHNAAJMwtV3hgpEWAuNaEm-45oDdyuhWHHreBGjjrKHAMnBVHolfnrHqK92becuGSpadeTpsmim2XDVijm4V0dRHKHrqDQYt2WWjR6GMBUqtaKJt0FrR-rZtzlNEiHTjIYzau1EsqY3Lso4dsf5DXjk8TDBzOwjAN4ZZd54DPRBbXAeS20ok3thDC2ljquIOOcsKjBRITQUdI-ooY7_dWVY7bm76FlU&ui_mode=redirect",
  "login_identity_id": "01J8EJ7Z0CFJTWTKE4VY97JD4G",
  "token_type": "Bearer"
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

link_customizations

object

Optional parameters to customize the behaviour of Finverse Link's UI to fit your implementation requirements

Show child attributes

user_present

boolean

Flag to indicate whether the user is present in the customer's app (to handle any 2FA action steps required during authorization). If user_present = true: Finverse will use the "user-present refresh" mode. This allows initiating a refresh for any institution. If user_present = false or omitted: Finverse will use the "background refresh" mode. This only allows refreshing when the institution's login_details.refresh_supported = true.

Response

Refresh queued

access_token

string

required

Link session token (referred to as link_token)

expires_in

integer<int64>

required

Token validity length (in seconds)

issued_at

string<date-time>

required

Token issue time

link_url

string

required

URL to launch the Finverse Link UI flow associated with this link_token, for the end-user to view the refresh status, or to provide 2F action inputs.

Example:

"https://link.dev.finverse.net/onboarding?token=dasdsa8erhiu7rey78r"

Finverse Login Identity ID for the Login Identity being refreshed.

token_type

string

required

Possible values: Bearer