Skip to content

Credentials

In Flanks, Credentials represent the authentication information (typically user and password) for a specific entity. All the data available in the identity using this authentication information will be stored and assigned to the credential.

Flanks securely store the final user's authentication information and uses it to access the target institution. This information is not accessible from outside Flanks (for example, using an API call) but is only used for this purpose.

Every credential has a unique identifier, which we call credentials_token. This identifier will be used to retrieve the information related to the credentials using the Aggregation API.

In summary, to get data from Flanks, you will need to:

  • Create new credentials for each different authentication needed.
  • Wait for Flanks to retrieve data from the target institution.
  • Retrieve the data for each particular credential.

Every credential is unique in the scope of your company. This means the same authentication information cannot be used twice. An error will be raised if credentials inside your organization are duplicated.

Credentials are added to Flanks using the Flanks Link.

It's worth noting that credentials are not people. It's not possible to do a 1 to 1 mapping between credentials and persons. Some credentials might hold information from multiple people (for example, for joint accounts) and, of course, a single person can own multiple accounts in multiple institutions. Flanks does not assign data to individuals because we don't have this concept in our Data Model. Any matching between credentials or their data to individuals must be done on your end.

You can interact with your credentials using the Credentials API

Data Update

The data that can be consumed for every credential is never "live" data. We don't fetch the data from the institutions every time. This would take too much time to keep our APIs usable. Instead, we always return the last version of the data we've fetched. The data of a credential is updated in the following cases:

  • When the credentials are created.
  • When the credentials were in Pending SCA status and that status is resolved.
  • When the credentials were in Blocked status and that status is resolved.
  • Every day we automatically retrieve the data of the credentials that don't require SCA and are not blocked.

Currently, we don't provide a way to update data on demand.

Lifecycle

Credentials can be in different statuses. You can check each credential status using the Credentials Status endpoint.

New credentials

New credentials are added to Flanks using the Link.

The final user must add their username/password for the entity in the Link. Additionally, some entities will require an SCA extra step.

If all these steps work, a new credential will be created.

Pending Status

Every credential starts with the Pending status. This signals that the credentials have just been created and Flanks still hasn't fetched any data.

Once the first data load is completed, the Pending status will be removed.

Pending SCA Status

Most credentials require a SCA validation to be created, and this is handled in the first user interaction.

However, for multiple reasons (for example, it's required every 90 days), at some point, Flanks will detect that a new 2FA authorization is needed.

This typically happens when doing periodical updates. Flanks tries to access the institution's website with the user/password provided, but the institution raises a 2FA challenge. Because this process is automatic, there's no final user involved to do the 2FA authentication.

In this scenario, Flanks can't access the information. All the information previously stored is still available, but it will not be updated. Also, if we keep trying we'll be at risk of blocking the access to the institution's website.

When this happens, the credential enters the Pending SCA status. Flanks will not try to update this credential until the situation is resolved. The final user needs to be present to unlock the credentials. This process is done using the SCA Flow with one Link.

Blocked Status

When starting a data update, Flanks can detect that the stored username/password doesn't work anymore.

This can be due to multiple factors, but the most common ones are:

  • The user/password have changed on the institution's website and have not been updated in Flanks.
  • The username is blocked on the institution's website for whatever reason and some manual process needs to be done with the institution.

In this scenario, Flanks can't access the information. All the information previously stored is still available, but it will not be updated.

When this happens, the credential enters the Blocked status. Flanks will not try to update this credential until the situation is resolved. The final user needs to be present to unblock the credentials. This process is done using the Reset Flow with one Link.