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:

• generating a permanent user access token;

• before opening the Webview, generating a temporary code from the permanent user access token;

• redirecting the user to the Webview, providing the temporary code as parameter, to let him pick up a connector and add a connection;

• handling redirection after the web steps.

You need to generate a permanent user access token for your new user which will create a new user on Powens side:

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

{
  "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.

Then before redirecting to the Webview generate a temporary code that you will provide to the Webview URL. This is so you're not opening the Webview using the permanent access token directly.

GET https://{domain}.biapi.pro/2.0/auth/token/code

Authenticate this request using the permanent access token you previously generated.

{
  "code": "{temporaryCode}",
  …
}

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

https://webview.powens.com/connect
  ?domain={domain}
  &client_id={clientId}
  &redirect_uri={yourCallbackUri}
  &code={temporaryCode}

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}?connection_id={id}

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

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.