Authenticate your end-user
This documentation explains how to authenticate your end-users in the Didomi Consents API via widgets. We will cover both One-Time Password and Magic Link workflows, as well as handling authentication from your server.
One-Time Password
One-time password workflows using Didomi APIs require you to implement two requests:
Generate the code to be sent by email
Verify the code provided by the end-user
Generate
To send your end-user an email with a 6-digit code*, send a GET request to https://api.privacy-center.org/auth/protocols/otp/generate
endpoint.
* Note: codes are valid for five minutes.
Verify
To verify the end-user code prompted in the widget, send a POST request on https://api.privacy-center.org/v1/auth/protocols/otp/verify
endpoint. As parameters, you need to specify the key
and in the payload, you need to define code
and organization_user_id
.
Magic link
To build a Magic Link workflow with Didomi APIs, you need to send a GET request on the https://api.privacy-center.org/auth/protocols/message/callback
endpoint and specify the following parameters:
Support multiple auth provider dynamically
Our SDK supports multiple authentication providers. To define the provider to be used, you can use the initiate endpoint and send a GET request on https://api.privacy-center.org/v1/auth/initiate
endpoint.
To support multiple authentication providers and allow your project manager to activate authentication workflows from the Didomi Console, you first need to ensure that your frontend supports all workflows before following the initialization process to determine the authentication provider to be used for end-user authentication.
Server authentication
In summary, this requires authenticating your backend with Didomi in order to retrieve a consent token for user login. This token needs to be passed to the frontend and made available in Local Storage.
Generate your secret key in Didomi Console
Our SDK will request Didomi APIs to retrieve previous consents, send new consents and authenticate your users in our system.
To do this, you need to create a Private API Key
.
If you have already generated an API Key, there is no need to generate a new one.
To create a new Private API Key
, follow these steps:
Click on My organization
Click on Private API Key
Click on the + New private API Key button
A modal appears, click on the Create button
Store the
key
and thesecret
in a safe place.
Authenticate your back-end with the Didomi API
You need to authenticate your backend and obtain a JSON Web Token that will be used for other API calls.
This requires you to create a session:
This access_token
will grant you access to Didomi APIs and you will be able to create a Consents Token on the user’s behalf.
Get Users Consents Token
We recommend obtaining a Didomi token at the moment of authentication, and sending it back to your front-end. This will allow your embeddable widget to log users in and retrieve their consents.
In your authentication controller, send a POST request to /tokens
endpoint.
Payload should include:
organization_id
can be retrieved in Didomi Console URL (required)organization_user_id
is the unique ID of the end user. This can be, for example, an ID or an email address. This is what will allow you to link consent to a user in your database, and it needs to be unique. (required)lifetime
is a token lifetime in seconds (optional)
💡 We recommend setting a lifetime that is equal to any other potential tokens you send on the front-end or any sessions. This will allow the user to be logged out from both APIs at the same time.
The API will respond with the created token in the id_token
field.
Add this token to your authentication endpoint response so it can be consumed by your front-end.
This id_token
is what we call a Consents Token. This token belongs to the end-user and allows them to change their consent and preferences.
Make the Didomi Token available in your frontend for the SPW to access it
The consents token needs to be passed to the frontend and made available so the SDK can read it.
Widgets offer two ways to read the token *:
* Note that our SDK will try to read the Token from the URL first and then in the Local Storage. Unless you want to force a specific authentication method, you don't need to set this property.
Didomi SDK can log your user in by reading didomi_auth_token
Local storage variable when window.didomiConfig.user.shouldReadTokenFromLocalStorage = true
.
Last updated