Consent and preference management API references

The OneWelcome Identity Platform provides access to the following consent and preference management APIs:

• Consent configuration API

• Consent management API

In CIAM solutions, user profiles typically contain the user’s date-of-birth, name, gender, home address, and so on. This allows companies to address consumers in a more personalized way, to analyze the characteristics of their customer base, and to adjust their offerings and marketing efforts accordingly.

Privacy aware consumers, however, might not be willing to provide companies with too much personal information. They don’t want their personal information to be used for data processing purposes that they don’t know about or haven’t given their consent for. Consumers want to be in control of their personal information.

Furthermore, the GDPR provides regulations to protect the privacy of consumers throughout the European Union. It prescribes rules for the processing of personal data. Companies must be transparent about which personal information is collected or processed. Processing of personal data can only take place based on certain legal bases. The most important legal bases are contractually needed or consent.

What is consent?

Consent is a mechanism of building trust between the user and an organization. Consent is a tool that allows the processing (collection, storage, use, and so on) of user data. For users, requiring consent offers choice. Users have the ability to express their preference: they can allow the processing of their data, or not.

The GDPR defines consent as "freely given, specific, informed and unambiguous indication of the data subject's wishes by which he or she, by a statement or by a clear affirmative action, signifies agreement to the processing of personal data relating to him or her". Users must be made aware of the consequences of their decision and how their data is or will be used.

Consent also needs to be granular, meaning that different types of consent are possible for performing different tasks if data is used in a number of distinct ways.

Consent APIs

The OneWelcome Identity Platform provides a CIAM solution that allows companies to use extended consumer profiles, puts the consumer in control of their personal information, and helps companies to be compliant with the GDPR. The OneWelcome Identity Platform CIAM solution includes privacy or consent APIs, and consent pages.

The consent management API focus is on consent according to the GDPR regulations. Consent given by a consumer to a data controller to do specific data processing on a type of personal data. This definition excludes consumer-to-consumer consent or mandates. The OneWelcome Identity Platform bases the consent definition on NISTIR 8112.

The consent management API provides access to the following resources:

• Processing purposes

• Attribute consents
• Document consents

Processing purposes

The processing purposes can be used as follows:

• Every type of personal information can be associated with one or multiple processing purposes.

• Part of the setup of these processing purposes is to record the legal basis for such processing. This legal basis is an attribute of each individual processing purpose.

• By querying the processing purposes that are administered in the OneWelcome Identity Platform, consumer facing portals and ‘MyPages’ can be transparent about processing purposes and their legal basis. Displaying this information to consumers contributes to building trust that their privacy is in good hands.

• Every processing purpose has a validity status that reflects the lifecycle of that processing purpose.

Attribute consents

For data processing that requires the user’s consent, the OneWelcome Identity Platform provides the attribute consent endpoint. Attribute consents serve the following use cases:

• When a user has given consent to use one of their personal data attributes for a certain processing purpose, this consent can be stored with the user’s digital identity.

• In a similar way, when users revoke such a consent, the consent can be deleted from the user’s identity.

• Applications that do the actual data processing can find out for an individual user whether a consent was given. If not, the application should not process the data.

• Consumer facing applications such as ‘MyPages’ can display to the user for what processing purposes their personal data is used including the ones with consent.

Document consents

The document consent endpoints allow you to store and retrieve consents given by the user on any of the consentable documents.

• When a user has given consent to a certain document or page, this consent can be stored with the user’s digital identity.

• In a similar way, when users revoke such a consent, the consent can be deleted from the user’s identity.

• Consumer facing applications such as ‘MyPages’ can display to the user for what documents or pages they have given their consent.

Authentication and authorization

The consent management API is protected to prevent misuse. Authentication is required to access the various endpoints. Aiming at the use cases indicated above, the OneWelcome Identity Platform distinguishes between server-to-server usage and self-service usage, or /Me:

• Server to server (S2S): Applications in the IT landscape that are involved with consents can be set up with credentials to access the protected consent management API based on basic authentication. When authenticated, such applications are authorized to perform full CRUD on the consents of any of the users.

• /Me: Consumer-facing web applications such as MyPage can invoke the /Me endpoint of the consent management API from a browser. In this case, the API is protected by requiring the user to be logged in. An authenticated user can access the consent management API and perform full CRUD on their own consents. The scope of consents that can be accessed or created is limited to only the consents of the authenticated user.

API usage flows

Registration flow

In support of a registration process, a typical sequence of calls from a registration process to the API would be:

• Obtain a list of consentable documents by doing a GET on documents, such as Terms-Of-Service and Privacy Policy.

• Obtain a list of processing purposes by doing a GET on processing purpose.

• Create a user through the OneWelcome Identity Platform SCIM endpoint.

• Store the user's document consents by doing a POST on the document consent endpoint.

• Optionally store the user's consent on processing purposes by doing a POST on the attribute consent endpoint.

Self-service flow

In support of a self-service page, such as MyPage, the following sequence could be used:

• Obtain a list of all processing purposes (for a given attribute).

• Obtain applicable consents that were given by the user.

• Display processing purposes on MyPage:

  • Contractual purposes are displayed for information and transparency.

  • Consented processing purposes are displayed with a check box enabled.

  • Processing purposes without consent can be displayed with a disabled check box.