--- source_url: "https://www.thalesdocs.com/oip/consent-prefs/index.html?utm_source=openai" title: Consent and preference management mirrored_at: 2026-08-04T01:03:17.902Z host: www.thalesdocs.com cited_in_42a: true mirror_canonical: "https://index.42a.ai/www.thalesdocs.com/oip/consent-prefs/index.html__q__utm_source_openai" --- > **Original source:** https://www.thalesdocs.com/oip/consent-prefs/index.html?utm_source=openai The consent and preference management module enables you to define customized consents, specify consent workflows, and register user consents. Consent is an important concept in the protection of natural persons with regard to the processing of personal data. The specific rules that need to be followed in Europe and for EU citizen data are determined by the [General Data Protection Regulation (GDPR)](https://gdpr-info.eu/art-7-gdpr/). The rules state among that the controller (such as a company offering its services) must be able to demonstrate that the user consented to the processing of their personal data, which means that the controller must register and keep track of its users' consents. **Examples of consents** - "I agree with the general terms and conditions of company A." - "I agree that company A, using services provided by company Y, uses my email address to send me a monthly newsletter." ## Types of consent The OneWelcome Identity Platform distinguishes between two types of consents: - **Document consents** give consent to a document and are often required to gain access to a company's service. - **Attribute consents** give consent to the use of personal data (referred to as **attributes**) for a specific purpose. They are always optional and indicate a preference of the user. ## Consent management API To help with consent and preference management, the OneWelcome Identity Platform provides a [consent management API](https://www.thalesdocs.com/oip/apis/consent_api/consent_management_oas/index.html) that you use to: - Define customized document and attribute consents. - Register user consents and log each action with regard to these consents. ### Consent management API information model The consent management API enables tenants to set up consent definitions. Each definition has one or more versions, which contain one or more documents. There is a distinction between objects for document consents and attribute consents. An **AttributeConsentDocument** can also be referred to as a **policy**. ![consent information model](https://www.thalesdocs.com/oip/images/consent-prefs/information_model_config_doc-attr.png) ## Consent objects and properties Object Unique identifier Example Description ConsentDefinition `name` terms-and-conditions The (Attribute)`ConsentDefinition` is a master data object that groups all information about one logical consent. For documents, it indicates whether the consent is mandatory for use of the tenant's services. Each `ConsentDefinition` can have one or more `ConsentVersions`. ConsentVersion `version` 2023.1 The (Attribute)`ConsentVersion` groups minor revisions of (Attribute)`ConsentDocuments` for multiple locales. This object also determines the opt-in method for registering consent to these documents and can contain an `endOfLife` property that specifies when these registered consents expire. ConsentDocument `version` `language` (`listOfAttributes`) 2023.1.1 nl-BE (email) The (Attribute)`ConsentDocument` represents one specific `version` of the actual document (stored in the `url`) or policy (`processingPurpose`) that must be agreed upon by users of a specific locale (`language`) to use the tenant's specified service. The `effectiveDate` specifies the moment in time when the (Attribute)`ConsentDocument` can obtain the [Document states](#document-states). Policies for attribute consents are further identified by the set of personal data (`listOfAttributes`) for which use consent is requested (such as email,firstName,phoneNumber). As a result, an `AttributeConsentVersion` can contain multiple policies with the same processing purpose (for example, newsletter), but with different options for the data that the user shares. Policies also store the `legalBasis` for processing the user's data. **Modification rules** - An **(Attribute)ConsentDocument** can be modified until its `effectiveDate`. Documents with `status:draft` can always be modified. - An **(Attribute)ConsentVersion**, and therefore the associated `optInConfig`, can be modified as long as **all** of its `ConsentDocuments` can be modified. - An **endOfLife** can be added to a `ConsentVersion` at any time. After it's added, it can be modified until its `startDate`. - An **(Attribute)ConsentDefinition** can be modified as long as **all** of its `ConsentVersions` can be modified. ### optInConfig property The opt-in configuration specifies how to process new opt-ins, that is, requests to register a user's consent. There is currently one opt-in method: - **Direct opt-in**: The request to register a consent is processed immediately. User action Request Back-end action 1 The user clicks the I agree button. The client requests to register the user's consent: [Register my UserConsent](#register-my-document-userconsent) The user's consent is processed (see [Registration of User Consents](#registration-of-user-consents)). ### endOfLife property To regulate the transition to a new `ConsentVersion`, an `endOfLife` can be added to the previous `ConsentVersion`. This property indicates when the transition starts (`startDate`) and when documents from the previous version are no longer valid (`endDate`). The `endOfLife` also specifies the duration of the period a user gets to agree to the new version (`gracePeriod`). This grace period starts at the moment the user receives the first invitation to accept the new `ConsentDocument`. The actual grace period for a specific user never extends past the `endDate` of the endOfLife (see user B in the [example of required consents](#example-of-required-consents)). ## Updating consents When consent documents require an update, new (Attribute)`ConsentDocuments` and, for major updates, new (Attribute)`ConsentVersions` must be created. This results in multiple documents for one locale within the same (Attribute)`ConsentDefinition`. A set of logical rules determines the state of each of these documents and the action which might be required from the user. ### Document states (Attribute)`ConsentDocuments` have a `status` property that indicates whether the document is a `draft` or is released (`active`). Documents also have a **lifecycle status** that is determined by a set of conditions (see table). For each locale in an (Attribute)`ConsentDefinition`, there is one **active** document, that is, the document that should currently be offered to (new) users. However, user consents to all currently **valid** documents grant access to the tenant's service. In contrast, user consents for **archived** documents are no longer accepted. Lifecycle status Requirements valid The `effectiveDate` lies in the past. If specified, the `endOfLife.endDate` of the (Attribute)ConsentVersion to which the document belongs, lies in the future. The `status` is not `draft`. active The document's `effectiveDate` is the most recent across all valid (Attribute)ConsentDocuments for the document's locale (`language`) that belong to the same (Attribute)ConsentDefinition. archived The `endOfLife.endDate` of the (Attribute)ConsentVersion to which the document belongs, lies in the past. In practice, there are three types of valid documents: 1. The active document. 2. Documents located in the same ConsentVersion as the active one (in other words, the active document is only a minor update). 3. Documents belonging to a ConsentVersion that is currently in its endOflife period (between `startDate` and `endDate`). ### Managing updates When (Attribute)`ConsentDocuments` reach their `effectiveDate`, they can no longer be modified (unless it is a draft). A new (Attribute)`ConsentDocument` must be created to apply minor (such as formulation) or major (content) changes. The below scheme explains how to manage these updates. Update Configuration User action required? minor (Attribute)ConsentDocuments with minor differences should be located in the same ConsentVersion. Documents for different locales do not need a simultaneous update. No. The (Attribute)ConsentDocument for which the user already gave their consent, is still valid. The user can continue using the service. major A new (Attribute)ConsentDocument must be created for each locale in a new ConsentVersion. Yes. Every user must consent to a new (Attribute)ConsentDocument. The transition to the new (Attribute)ConsentVersion makes use of a grace period. - During the grace period: The (Attribute)ConsentDocument for which the user already gave their consent, is still valid. The user may continue using the service, but should be reminded of the need to renew their consent. - After the grace period: The user's access to the service will be denied until the user agrees to the currently active (Attribute)ConsentDocument. Warning The grace period is defined in the endOfLife of the ConsentVersion to which the previously accepted (Attribute)ConsentDocument belongs. **Attribute example** The minimal set of attributes required to subscribe to a newsletter change from `email` to `email,fullName`. The policy with `listOfAttributes:email` is thus no longer valid. Because this is a major change, a new `AttributeConsentVersion` must be created and all `AttributeConsentDocuments` that are (still) applicable must be (re)created. In addition, an `endOfLife` must be specified for the previous `AttributeConsentVersion`. #### Example of required consents ![consent example](https://www.thalesdocs.com/oip/images/consent-prefs/consent_example.png) The above image shows an example where user consents are required before, during, and after the `endOfLife` period associated with the `ConsentVersion` **Green**. All users in the example request a Spanish `ConsentDocument`. - Users A, B, and C already gave their consent for ConsentDocument G1 and are only invited to agree with a new document after `startDate`. - New users W and X are offered a different ConsentDocument due to the timing of their requests in relation to the `effectiveDate` of ConsentDocument **G3**. - New user Y (in contrast to new user Z) still receives a ConsentDocument from the **Green** ConsentVersion, since the recently created **Blue** ConsentVersion does not yet have an effective ConsentDocument. - User A gets the full grace period, while user B does not because the remaining time to `endDate` is less than `gracePeriod`. User C requests access after `endDate` and receives no grace period. ### Good practices for ConsentVersion The transition to a new ConsentVersion is most efficient when following a few good practices: - The new ConsentVersion should be ready to be used at the `endOfLife.startDate` of the previous ConsentVersion: - ConsentDocuments should be provided in (at least) the same locales as provided in the previous ConsentVersion (to avoid the absence of a valid document for a specific `language`). - The first ConsentDocument(s) in the new ConsentVersion should have an EffectiveDate equal to the `endOfLife.startDate` of the previous ConsentVersion. - From `endOfLife.startDate` onwards, no new ConsentDocuments should be added to the ConsentVersion associated to the endOfLife. ## Consent registration ### Consent registration information model The consent management API handles the actual registration of user consents. When user consents are processed, the OneWelcome Identity Platform stores two types of information: 1. A UserConsent object contains the user's identifier and the properties needed to uniquely identify an (Attribute)ConsentDocument. These objects are used to check whether a user gave their consent for a specific document. 2. An audit-log (RegisterEvent) stores all user requests and actions for audit purposes. ![alt\_text](https://www.thalesdocs.com/oip/images/consent-prefs/information_model_consent_userconsent.png) An (Attribute)ConsentDocument is uniquely identified by four properties: - The (Attribute)ConsentDefinition's `name` - The (Attribute)ConsentVersion's `version` - The (Attribute)ConsentDocument's `version` and `language` ### Conceptual example of audit-log Time Consent User Action `2019-11-10T23:00:49Z` terms\_conditions\_2019 John Doe Registered via direct opt-in method. `2020-01-10T04:50:02Z` daily\_newsletter Jane Doe Token requested for double opt-in method. `2020-01-10T04:55:05Z` daily\_newsletter Jane Doe Registered via double opt-in method. `2020-01-10T20:03:00Z` terms\_conditions\_2020 John Doe Registered via direct opt-in method. `2020-01-10T20:10:32Z` terms\_conditions\_2020 John Doe Revoked. ## Endpoints overview The following diagram shows the configuration and consent management endpoints for document consents. For attribute consents, a similar set of configuration endpoints is available. ![endpoints overview](https://www.thalesdocs.com/oip/images/consent-prefs/endp_consent_document.png)