Skip to content

Connect Sessions

Note

In this document we'll use the terminology of "connections" and "connection id". These terms are replacing "credentials" and "credentials_token", but while different generations of our APIs are still in use, keep in mind that those therms can be used interchangeably.

Connect Sessions help you handle the lifecycle of your connections. You will use Connect Sessions when you need any end user action. You can use them to:

  • Create a new connection
  • Update the credentials of an existing connection
  • Solve a MFA challenge

For each action, we will create a new session. These sessions are unique and non-reusable. Each session have a unique URL where you need to redirect the user to.

This URL will be valid until the session expires or the user finishes the process. The widget rendered in the URL will look like this:

Choose connector

Provide Credentials

Challenge

Success

Sessions Worflow

You can manage sessions' lifecycle using the Connect API.

A simplified version of the workflow is:

  • You create a session using the Create Session endpoint. This will return a session ID and a URL.
  • Redirect your user to the URL provided in the response. The user will go through the Connect Widget flow.
  • You can check the status of the session at any time using the List Sessions endpoint.
  • When the user finishes the process, we will redirect the user to the redirect_url you provided in the configuration. We will include the session_id parameter in the URL.
  • You can check if that particular session was successful and a new connetion was created using the List Sessions endpoint.

Lifecycle

Session Configuration

You can configure some aspects of the widget the user will interact to. The complete list of configuration options can be found in the Session Configuration Model.

If you set the connection_id option, the session will be used to unblock a connection. If it's not set, the session will be used to create a new connection.

If you set the connector_id option, the user will not be able to change the connector in the widget: they will land on the "provide credentials" screen. If it's not set, the user will be able to select a connector from a list.

New Connection

To create a new connection, you need to create a session and redirect the user to the URL provided in the response.

Once the user finishes the process, we will redirect the user to the redirect_url you provided in the configuration. If the process was successful, we will inmediately dispatch an internal action to fetch all the data for that connection.

Unblock a Connection

Once created, a connection might need user interaction to keep refreshing its data. For example, a connection might require the user to solve a MFA challenge or the user might have changed their credentials in the website.

In all these scenarios, you can use a session to unblock the connection. You'll have to provide the connection_id of the connection you want to unblock.

When you redirect the user to the session URL, the widget will ask the user to provide any information required to unblock the connection.

Monitoring Sessions

At any point, you can use the List Sessions endpoint to understand the status of your sessions.

This will be used when a user is redirected to the redirect_url you provided in the configuration, but you can also use it to check the status of your sessions, finished or not.