Add a first user and connection

Add a first user and connection

If you want to initiate payments, you do not need to add user/connection, please refer to the pay guide.

Prerequisites

To start interacting with our API, make sure you have setup a domain and a client application in the administration console.

Users and connections

User scope

Users of your application exist in our API. All data collected and exposed through our services is organized and scoped by users. We enforce isolated access to user data by issuing user-scoped access tokens, shared secrets that let you both authorize with our API and identify the relevant user you want to interact with.

You are responsible for keeping these tokens safe, and maintain the association with your own user registry.

Connections

User data arise from connections. A connection materializes the link between a user and one of the connectors (banks or billing providers) we support. Creating a connection requires the end-user to authenticate with the connector. As long as the connection is active, we take care of synchronizing user data and expose it.

You will need to let your users add a first connection before you can access its banking or billing data.

Adding a new connection

You can use our integration demo to experiment with the different steps described below.

The simplest way to perform a connection setup is to use our Connect webview, a set of web-based endpoints that complement your domain API. It will take care of letting the user choose his bank or provider, gather credentials for later sync and manage consent to the individual bank accounts or document subscriptions he wants to share with your service, enforcing GDPR requirements.

The steps include:

• redirect the user in a browser to the webview to let him pick up a connector and add a connection;

• handle redirection after the web steps and get the temporary code;

• exchange the temporary code for an access token.

For the most simple configuration, present the following URL to your user (new lines are only added for clarity):

https://{domain}.biapi.pro/2.0/auth/webview/connect
  ?client_id={clientId}
  &redirect_uri={yourCallbackUri}

You will need to provide the client_id of the client application created in the administration console, and a redirect_uri to use as a callback that must match the white-list defined in the console.

To optimize user experience, we encourage you to open the webview in a standalone fully-capable browser following our best practices. The webview appearance can be customized in the Administration console, and its behavior can be configured using additionnal parameters.

After the user has completed all steps in the webview, he will be redirected to your callback URL:

{yourCallbackUri}?code={authorizationCode}&connection_id={id}

You need to extract from the URL the code parameter (beware of URL-encoding), and exchange this temporary code against a long-lived access token scoped to the newly-created user:

POST https://{domain}.biapi.pro/2.0/auth/token/access

{
  "code": "{authorizationCode}",
  "client_id": "{clientId}",
  "client_secret": "{clientSecret}"
} 

{
  "auth_token": "{accessToken}",
  …
}

This step involves sending your client secret (a sensitive data), you must perform it from a secure environment.

The connection flow can also lead to errors, reported with the error and error_description parameters, your implementation must handle them gracefully.

As an alternative, you can manage the creation of the user yourself using the /auth/init endpoint, and open the webview with a temporary code. In this case the webview will add the connection to the provided user, and no code exchange is required after the redirection.

If eligible, you can build your custom connection implementation instead of using our webview.

Use the access token

Congratulations, you have been provided an access token that you must save, and that you can use to interact with all our products!

As soon as a connection is created, it gets synchronized (in background). If you have configured webhooks, data will be pushed as soon as the synchronization complete.

After creation, you should provide your users a way to manage their connections (add/delete, or manage consent to accounts). You can use our Manage webview for this or create your own implementation. Also, you need to properly handle the various connection states that may occur afterwards.