The Consent Service is an HTTP-based REST API hosted by the PingDirectory Server or PingDirectory Proxy Server. The service enables the collection of consents from application users, the enforcement of consents, the management of consents by users, and auditing of consent actions. This service helps companies to meet GDPR mandates and promotes transparency for users submitting data through applications.
Anytime an organization wants to collect and use the data of its users, it should carefully consider its right to do so from the perspective of the user. If the user would expect the organization to use his or her data in a certain manner in order to conduct its business, then it is reasonable for the organization to not require explicit user permission to do so. In other circumstances, in order to retain the trust of its users, the organization should get user permission first. Under the General Data Protection Regulation (GDPR), these miniature data agreements between user and organization are called consents.
Consent requests are formulated and presented to users through consent definitions which encapsulate the terms of the miniature data agreement. These terms may result in a single question that prompts users for an ALLOW/DENY response, or they may result in a more complex agreement, with several prompts that solicit a more fine-grained response. Every consent definition, whether simple or complex, is associated with at least one localization, which specifies the locale and the localized terms of consent. For a user to make an informed decision regarding his or her data privacy, the localized terms include a description of the user data and the purpose for which the organization wants to use the data.
The consent definition, the response by users, date and time, session information, and other details are stored for future reference. All information that constitutes the consent request and response becomes part of the searchable consent record in the data store.
For more information about the Consent Service, see Introduction to the Consent Service and Consent API.
The Consent API includes the following entities.
A consent definition represents the distinct type of a data agreement to which a user must grant permission. For example, “Share my application data.” is a consent definition. All consent definitions have basic properties like an id or displayName. A consent definition can include other custom parameters, if needed.
The definition resource in the Consent API model represents the container for the consent definition localizations, where the localizations sub-resource defines the localized consent definition text presented to users.
Consent localizations define the prompt presented to users in the specified language for the identified locale. The locale value must be a BCP 47 compliant language tag, like en-US. The prompt text is defined by two properties, the data which is being collected or shared, and the purpose for doing so.
A consents resource contains the consent record data. The consent record includes the consent definition details, create and update timestamps, and values for subject, status, actor, audience, collaborators, and other attributes.
The Consent API represents consent resources using JSON. Non-error responses are sent using the application/hal+json media type. Error responses are sent using the application/json media type.
Resources served by the Consent API follow the conventions of the JSON HAL (Hypertext Application Language) specification. Resources use the application/hal+json media type and may include the following read-only fields.
_links
An object whose fields are link objects (or arrays of link objects) that refer to related resources. Every resource includes a link object called self, which refers to the resource itself.
_embedded
An object whose fields contain embedded related resources. This field never appears by default but may be included if the client specifies the expand parameter.
A link object may contain the following fields.
href
The related resource’s URI.
hreflang
The related resource’s locale value. This is only used if the related resource is a consent definition localization.
Consent records capture an individual’s consent decision. The consent records API is read-write. Access control differs for privileged and non-privileged requesters: A privileged requester can take action on any consent record. An unprivileged requester can take action only on their own consent records. For more information, see Getting started.