Tips for using the API

A few tips on how to make the best use of our API.

Contents of this documentation:

The documentation is available at the following addresses:

• backend core: https://core.fairandsmart.com/doc/api.html

• backend data: https://data-fr01.fairandsmart.com/doc/api.html

• backend timestamp: https://tsa.fairandsmart.com/api-doc

Setting up a technical account for using the API

While in absolute terms it is possible to use any account with access to the organisation to make API calls, it is preferable to create a technical account dedicated to this purpose.

On the one hand, this practice mitigates the risk of using an employee's account, which can lead to a loss of access to the application - change of position, departure from the company - but also allows roles to be configured as finely as possible so as to restrict possible operations to the strict minimum.

The first step is to define a specific role and assign only the operations it will need, such as Generating a consent collection link and Assessing the status of a consent with a request.

The second step is to invite this technical user: to do this, follow the employee invitation procedure specifying that they should benefit only from the newly created role.

Then proceed with the onboarding of the technical account in a standard way.

Access authentication

Access to the API is via a token obtained via OAuth2 from the authentication server https://auth.fairandsmart.com/ .

As access tokens have a much shorter lifetime than refresh tokens (5 minutes vs. 30 days), it is advisable to keep a copy of it to avoid having to log in again for each REST call, and to renew it only if necessary.

This operation also allows you to change the password of the account used to retrieve refresh and access tokens asynchronously, and not to cut off access to the API during the time it takes to propagate the change in production of the code of your application.

Choosing a User ID when generating a consent form

A User ID must be passed to the generation calls of the consent collection endpoints (https://core.

fairandsmart.com/doc/api.html#operation/getConsentEndointJson). Insofar as this identifier is clearly indicated in the consent register, its definition must have appropriate guarantees.

We therefore recommend that you avoid choosing a User ID that makes it possible to directly identify a user, by using a pivot that requires access to your IS to be resolved.

In particular the use of first names, email addresses, SS-numbers or even a reversible obfuscated version such the base64 encoding of these attributes should be avoided.

To find out more

• User account management