VisionsTrust Documentation

Quickstart Guide

Welcome to the VisionsTrust quickstart and implementation guide. You have already done a couple things here, let's recap.

Organization Categorization

Upon creation of your VisionsTrust account, you were prompted to categorize your organization. This will list your organization with other organizations of the same category within the catalog and will help both organizations and users find you.

General Organization Information

You then entered a general description for your organization. This is public information which allows other organizations and end-users to know what your organizations does.

More information on your organization will be required later on in this guide, and you'll find a dedicated web page for exactly that.

Service declaration and information

By categorizing your services and describing them, you give the opportunity to other organizations to know what kind of service you offer, and we can make a better job at listing your service amongst services of the same type

The information on your services can be accessed and modified at any time on your dashboard later on.

Data interest and declaration

You then informed us of data you are interested in and data you are able to share.

By letting us know what type of data you are interested in, we will be able to show you services and organizations that are able to share this kind of data.

By declaring data from your organization, you allow organizations to make a request on the access of your data. You will then need to accept this request, which we'll cover in a moment

Web application configuration

Now that we've recapped what you did until now, let's see how we can finish configuring your service on the app before moving on to the necessary code to implement to communicate with our API to enable data exchanges.

To be able to come back to wherever you paused your configuration, each step will show you a button to let us know when you're done with that particular task. This allows us to get you back to where you stopped directly and also know where organizations start having issues so we can improve our guides.
You can follow your progress on the top-left of this page.

General Information

Now that you're done with the initial steps, assuming you are logged in to your VisionsTrust account, navigate to the governance information page.

On this page, you will need to give us some additionnal information about your organization.

What is this used for ?

When agreeing to a data exchange configuration with another organization, a contract is generated. The information that you enter on this page are the ones that will appear on the data sharing contract generated.

Declaring conditions on your data

Now that your data has been declared, you are able to create custom conditions and terms of use on your datasets.

Your declared terms of used are found under Gouvernance > Conditions d'utilisation.

From here simply fill out the form for the conditions to be generated.

In the following section you will be able to declare a dataset based on your declared data and associate these conditions and terms of use to it.

Declaring Datasets

Based on the data you declared earlier, you can create datasets with one or more of your declared data for them to be associated with the terms of use you generated before.

Your declared datasets are found under Gouvernance > Datasets.

Follow the instructions on this page to generate a dataset and associate one of your declared terms of use to it.

When another organization requests data in your dataset, the contract will show these conditions for the other party to accept.

Authorizing another organization to access your data

To start exchanging data with other organization, there's a couple things to do. The initial step is to authorize globally another service to access your data. To do that, go to the exchanges page and explore the available services until you find the one that fits your use case.

By clicking on that service, you will be prompted to authorize data exchanges with it.

If this other service then agrees to this exchange, the global authorization is active between your two organizations and data exchanges can be configured.

Please note that if the authorization has not been made by both parties, further configuration of the data exchange is not possible.

Requesting Data

If the other party has confirmed the authorization, you can now configure data exchanges. In order to request data, navigate to the same exchanges page and get to the authorized service.

Now that the authorization is active, you will notice that the information you see is different from the initial information you saw for this service.

Listed on the left are all the types of data that this other organization is willing to share. And for each of them, you can request access to one or more of your services.

Data requests are made for a specific purpose, this is why you request data for one of your service and not globally. The provider of this data will then get a choice to authorize data per service.

Accepting Data Requests

If you have received incoming data requests from other organizations, you will be able to view them on the "demandes d'import" page.

This page lists all organizations that have requested your data as well as the amount of different requests you've received.

By viewing one of these requests, you are taken to a page summarizing the request, informing you of the data requested as well as for what purpose it has been requested. You now have the option to accept or deny the access to individual data for this exchange.

A bit of useful information

Even if endpoints will be described here, there are resources to help you along the way.

• - OpenAPI Documentation (Swagger)
• - Public repository with integration templates for NodeJS (backend) and vanilla javascript (frontend)

Security

Every request you will make towards our API needs to be authenticated using a Bearer Authentication with an Authorization header.

You will need 2 keys in order to do that. Your Service Key and your Secret Key. Both are obtained through the Paramètres page.

The token to pass in the Authorization header is a JWT token generated from encoding the following object with your secretKey:

payload = {
    serviceKey: YOUR_SERVICE_KEY,
    iat: now,
    exp: now+5min
}

                    

Here's an example using jsonwebtoken npm module in NodeJS

const token = jwt.sign(
    {
        serviceKey: serviceKey,
        iat: (new Date().getTime())
    },
    secretKey,
    { expiresIn: 5 * 60 }
);

                    

Once you have your token, each request to our API will need the header such as :

Authorization Bearer JWT_TOKEN

                    

Registering your users in VisionsTrust

For you to be able to generate consents and activate a data exchange for a specific user, you first need to register your user inside VisionsTrust.

This step is important as if you have no declared user, you will not be able to generate any kind of consent popup based on a data exchange configuration.

The choice of when to register the user inside Visions is up to you, however here are a couple use cases that other partners use for user registration.

For new users, you can use the first method. For existing users, you can use whichever you choose.

If you plan to be a Data Consumer, having the registration on signup because users will be able to activate data exchanges from a partner platform to your platform and be requested to create an account on your platform to finalise the exchange. This is handled in this special case.

To register a user inside VisionsTrust please refer to this endpoint of our OpenAPI documentation.

Integrating the endpoints to activate the data exchange

To implement the data exchange functionality and participate in the network, you will need to configure and expose a couple of endpoints on your API. Before jumping into the technical requirements of the endpoints, take a look at the complete data exchange process on the diagram below.

Lets walk through it step by step

Suppose SI is the service importing data and SE is the service exporting data. For details on the endpoints to configure on your service, click the links in the explanation or scroll down to the next section.

Endpoint: Consent Export

This endpoint is meant to be integrated on the organization exporting data.

example: POST "/consent/export"

                            

This endpoint is called by Visions and receives the following in the request body:

{
    signedConsent: SIGNED_CONSENT
}

                    

The content of the signedConsent is a signature of the content of the consent using RSA and the node crypto library.

In order to decode it you must use the public key described below.

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAs7c5/FFH8/52qhFoWXMS
zesJOCkPTB6381lRka7Egs+MQtTmcy0T+ipIpN7yWrUH2/vTcbRketbe/KdB7OEc
c6wfkH1lqPWH0BqszyKGDTO5HI+tbTcHX737FbV+X+xdx4vq7opQ65+eZ09zfagy
m5VUJiDinXlHfeAKkG2QjWR2yrjA4euIYZRaq1cj+zVHeTnHUtI/P8ANt4VGcWT7
M6HmLbrH12Ueglvv7VfSbhkjGeEYeoopXCEz2eZyOLafRSssh6YWEpaPB3G8BZRS
wCMbUajSnoUC+626AjLvXNt39wsWYCbQNtR3Zp09WtXL5arY4jJisPYxe+VWRUNb
9NYHVb1FuMFr8jCxdb0czISaRm9PKCW88Kv6qt6PC7Kzxc+kIGwf9H8nvBBxJYuU
49LRPHyEz+Di8DfsZuVCy1pkVheHwTQWycoi8jD86Rghj1vg9BYhW7n9BqQLLvxb
iF/QYTuxFaPz4YjXpfsgjx3hr30cJuSmSn2AeBgl5+e5W7qGqS8Hw9/JqCmF+0Y2
G3QLwnuaN6Ha9rTmB88HERP4OULmBNYpD+CTEdE/tglFuJYB9HrglmkXA8QK6taP
wJP5watrK2izg2w6/WFbY0mDEh6Q9hZ0ZDqBZGPuU0bIlLPCn695gVM8/420YeJZ
Gzl0WoFWTSg+E+vu9GeX55sCAwEAAQ==
-----END PUBLIC KEY-----

                    

You can find an example of how it can be done in NodeJS in the public repo.

You will then need to generate an access token for the Import Service to use when requesting the data to you later on. This access token should not exceed 50 characters as it would break the limit of the signeable content size method that we use and break the process.

Important

Now that you have exposed this endpoint on your API, you need to inform the corresponding URL in the consent export url field of your service settings.

Endpoint: Consent Import

This endpoint is meant to be integrated on the organization importing data.

example: POST "/consent/import"

                            

{
    signedConsent: SIGNED_CONSENT // Bundled with access token
    serviceExportUrl: "https://example.com/data/export" // The data export endpoint of the export service
}

                        

Endpoint: Data Export

This endpoint is meant to be integrated on the organization exporting data.

example: POST "/data/export"

                            

{
    signedConsent: SIGNED_CONSENT // Bundled with access token
    dataImportUrl: "https://example.com/data/import" // The data import endpoint of the import service where you will send the data
}

                        

Endpoint: Data Import

This endpoint is meant to be integrated on the organization importing data.

example: POST "/data/import"

                            

This endpoint receives the data coming from the Export service as well as a couple additionnal information.

The request body will look like so :

{
  "data": {} // The data coming from the export service -> The format should be decided between the two services,
  "user": "string" // The user id of your service, so you know for which user you need to register the data
  "signedConsent": signedConsent // The signed consent
}

                    

If you need some additionnal information such as the user email from the consent, you still have the option to decrypt the signedConsent. To do that, please refer to the section concerning the consent decryption in the consent export endpoint.

Activating A Data Exchange For A User Without An Account In The Importing Service

When a user activates a data exchange from an exporting platform and doesn't have an account in the platform that will receive the data, he has the option to specify that on the consent popup.
After validation, Visions will then build a redirection url made up of the registration url you informed in your service settings and two extra parameters like so:

"https://example.com/signup?consentId=THE_CONSENT_ID&visions=THE_ENCRYPTED_CONSENT_ID"

                    

Essentially, the export service will use this url to redirect the user to your signup page that should be ready to interpret these parameters. Whether you want it to be on your existing signup page, or wish to create a specific page to handle this use case is up to you.

Following are the steps that should happen when arriving on this page.

Generating Data Exchange Consent Popups for your users

Now that pretty much all of the backend is implemented, you are able to present data exchange popups to your users based on the exchange configurations you have made within the VisionsTrust web application.

There are two types of popus you can generate, a popup to export data if you are providing data, and a popup to import data if you have requested data from other sources.

Below are examples of how partners have integrated and designed consent popups based on the information we send back.
Notice that on the last one, there is a checkbox asking for the user to specify if he has an account in the receiving service. This is an important use case that is covered below.

Retrieve Information On All The Available Consent Popups

To retrieve the information about the popups you can present to your user, you can retrieve the information about all of your configured exchanges with other organizations.

The API to call is described here, and will allow you to then request individual consent popups by providing some of the information you receive.

Let's take a look at the information you receive

{
  "export": [ // The list of available popups for exporting data
    {
      "service": "string", // The name of the service towards which you will export data
      "purposes": [ // The list of configured exchanges with this service
        {
          "name": "string",
          "id": "string", // ! This id is necessary for the popupRequestEndpoint request body
          "flow": "export",
          "popupRequestEndpoint": "https://visionstrust.com/v1/popup/export", // The endpoint to call to get this consent popup
          "popupRequestMethod": "string",
          "details": "string"
        }
      ]
    }
  ],
  "import": [ // The list of available popups for importing data
    {
      "service": "string",
      "purposes": [
        {
          "name": "string",
          "id": "string",
          "flow": "import",
          "popupRequestEndpoint": "https://visionstrust.com/v1/popup/import",
          "popupRequestMethod": "string",
          "details": "string"
        }
      ]
    }
  ]
}

                        

Based on this information you will then be able to generate export or import consent popups depending on what you have configured and will be available.

Data Export Consent Popup

Now that you have the information from the previous section, if you have an export consent popup available, you can call the popupRequestEndpoint to generate it. However, you must specify both the email of the currently logged user in your platform and the purpose id as described in the corresponding API.

Using the data gotten from the response to this call, you are now able to populate and build the consent popup for your user. If you want, we provide in our public repository, a HTML template for the popup (fully cuztomizeable) as well as some front end code to populate the popup.

Please note you may find yourself in one of 2 cases concerning the reception of the emailImport (the email from the user in the import service) when retrieving popup data.

Data Import Consent Popup

Now that you have the information from the previous section, if you have an export consent popup available, you can call the popupRequestEndpoint to generate it. However, you must specify both the email of the currently logged user in your platform and the purpose id as described in the corresponding API.

Using the data gotten from the response to this call, you are now able to populate and build the consent popup for your user. If you want, we provide in our public repository, a HTML template for the popup (fully cuztomizeable) as well as some front end code to populate the popup.

Starting The Export Data Exchange

In order to activate the export data exchange protocol, you need a couple of information. The details on how you should build your request is on this API but let's go over the details of what is required.

{
  "datatypes": [ // The list of selected data by the user
    {
      "id": "string", // The id of the datatype (provided when generating the popup)
      "datatype": "string", // The name of the datatype
      "checked": true // If the user has selected it
    }
  ],
  "emailExport": "string", // The email of the user currently logged in
  "emailImport": "string", // The email of the user in the importing service
  "userKey": "string", // The userKey received when registering the user inside VisionsTrust
  "purpose": "string", // The id of the purpose for which this exchange is taking place
  "isNewAccount": true // Whether or not the user has checked a box saying he wishes to create an account in the Import service
}

                    

An example of how this information can be taken from the popup and placed into this request is shown here in the public repository.

Starting The Import Data Exchange

In order to activate the import data exchange protocol, you need a couple of information. The details on how you should build your request is on this API but let's go over the details of what is required.

{
  "datatypes": [ // The list of selected data by the user
    {
      "id": "string", // The id of the datatype (provided when generating the popup)
      "datatype": "string", // The name of the datatype
      "checked": true // If the user has selected it
    }
  ],
  "emailExport": "string", // The email of the user inside the exporting service
  "emailImport": "string", // The email of the user currently logged in to your platform
  "userKey": "string", // The userKey received when registering the user inside VisionsTrust
  "serviceExport": "string" // The name of the Exporting Service
  "purpose": "string", // The id of the purpose for which this exchange is taking place
}

                    

As you might have noticed, the import popup can contain multiple exporting services but you only provide one service export name in the request. This is because you need to make consecutive calls for each data source from the consent popup and build the request body accordingly for each service.

An example of how this information can be taken from the popup and placed into this request is shown here in the public repository.