Skip to content

Connections

Connections used to be called credentials

A connection is what we used to call a "credential", and its connection_id is the same value our APIs return as credentials_token. We are moving to "connection", but the old names are still in use: same object, same identifier, two names.

A connection represents one set of access details your end user holds at a financial institution. Flanks uses it to log in to the institution, and everything we retrieve there is stored against that connection.

Flanks stores the end user's access details encrypted and uses them only to access the institution. They are never readable from outside Flanks: no API returns them.

Every connection has a unique identifier. You use it to retrieve the data of that connection through the Aggregation API, where it is the credentials_token parameter.

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

  • Create a connection for each set of access details.
  • Wait for Flanks to retrieve the data from the institution.
  • Retrieve the data of each connection.

Connections are created with a Connect Session: the end user provides their access details in the Connect Widget, some institutions add an SCA step, and if every step succeeds a new connection is created. You can list, inspect and delete your connections with the Credentials API.

Uniqueness

Within your environment, the same username and password for the same connector will not produce a second connection.

If an end user goes through a Connect Session with access details that already exist, the session does not fail: Flanks reuses the existing connection, and the session finishes successfully returning the connection_id of the connection that was already there. Some institutions also let us identify the account after logging in, so a connection can be recognised as a duplicate at that point and resolved the same way.

Note

The legacy and deprecated Flanks Link flow behaves differently: it reports a duplicate as a CREDENTIALS_ALREADY_EXIST error.

Connections are not people

A connection is not a person, and there is no 1-to-1 mapping between the two. A single connection can hold data belonging to several people — a joint account, for example — and a single person can hold accounts at several institutions, which means several connections.

Labels let you carry your own identifiers on a connection. They are key-value pairs of your own: you set them when creating the Connect Session, they are copied to the connection, and they are returned when you list your connections.

Data Update

The data you read from Flanks is never live. We don't query the institution on every request — that would make our APIs too slow to be usable. We always return the last version we retrieved.

The data of a connection is updated:

  • When the connection is created.
  • When a connection in Pending SCA or Blocked state is unblocked.
  • Automatically, following the refresh schedule of its connector, which is normally once a day. It also depends on your environment's configuration: automatic refresh can be turned off for an environment, so that none of its connections are updated automatically. Connections in Pending SCA or Blocked state are never refreshed.

Lifecycle

A connection has no single status field. The Credential Status endpoint returns an object, and the states below are read from its fields.

Pending

pending is true.

Every connection starts here: it has just been created and Flanks hasn't finished retrieving its data yet. pending becomes false when the first load finishes, with or without errors.

Pending SCA

sca_token is not null.

Most connections need an SCA validation to be created, and that is handled during the end user's first interaction. Later on, the institution can require a new SCA authorisation.

During an automatic refresh there is no end user present to answer a challenge, so Flanks avoids refreshing a connection whenever it can tell that SCA will be required. That is not always possible to know in advance: sometimes Flanks logs in with the stored access details and the institution raises a challenge that nobody can answer.

When that happens, Flanks can't retrieve data. Everything already stored stays available but stops being updated, and Flanks will not retry until the situation is resolved: retrying would risk locking the access at the institution. The end user has to be present to unblock the connection, as described in Unblock a Connection.

Blocked

blocked is true.

When starting a refresh, Flanks can find that the stored access details no longer work. The most common reasons are:

  • The end user changed their username or password at the institution and it has not been updated in Flanks.
  • The username is locked at the institution and a manual process with them is needed.

As with Pending SCA, everything already stored stays available but stops being updated, and the end user has to be present to unblock the connection. See Unblock a Connection.

You can also block a connection yourself with the Block Credentials endpoint, to take it out of the automatic refresh.

Deleted

Deleting a connection is permanent. Flanks removes the stored access details and every piece of data retrieved for it, and none of it can be recovered afterwards. Use the Delete Credentials endpoint.