Consent records
When a user responds to a consent request, a consent record is created to capture the data. The Consents service implements functions to check for existing consent records, get a specific consent record, and create new or modify existing consent records.
Check consent records
You can get all consent records associated with a specific individual, and that individual can be either the subject of the consent (the person whose data is collected or shared) or the grantor of consent (the person who responded to the consent request).
Checking consent records (getting a list of records) supports specifying either the subject
or actor
query parameter to focus the search. These parameters identify either the person whose data is being collected or shared (subject
) or the person who granted or denied consent (actor
). In many cases, the subject
and actor
are the same individual.
Note: Specifying the subject
and actor
query parameters are not required by the client. If these parameters are omitted, a subject
value is inferred from the authentication context. For example, if the client uses bearer token to authenticate, the token subject is used.
The query parameter can be fine-tuned by adding another consents resource attribute to the query. Here is a sample:
"https://<server>/consent/v1/consents?subject=JohnDoe&definition=share-my-email"
For this request, the response data will show only the consent records for the subject
(John Doe) in response to a specific consent definition resource definition
(share-my-email).
Filtering result data
The following attributes can be used in a filtering expression for the GET /consents
operation:
-
subject
The individual whose data is being collected or shared through a consent grant.
-
actor
The individual who granted the consent request.
-
definition
The consent definition ID.
-
audience
The entity that requested or received the individual’s response to the consent request.
The following sample shows the GET /consents
operation to return the consent records associated with the specified individual.
curl -X GET "https://<server>/consent/v1/consents/?subject=JohnDoe" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"
The response data shows all consent records associated with subject
John Doe:
{
"_embedded": {
"consents": [
{
"_links": {
"definition": {
"href": "https://<server>/consent/v1/definitions/share-my-email"
},
"localization": {
"href": "https://<server>/consent/v1/definitions/share-my-email/localizations/en-US",
"hreflang": "en-US"
},
"self": {
"href": "https://<server>/consent/v1/consents/f0c0ac1d-a493-426d-9211-224255145d28"
}
},
"actor": "JohnDoe",
"audience": "client1",
"createdDate": "2018-03-26T18:43:28.616Z",
"dataText": "Share your email address",
"definition": {
"currentVersion": "1.0",
"id": "share-my-email",
"locale": "en-US",
"version": "1.0"
},
"id": "f0c0ac1d-a493-426d-9211-224255145d28",
"purposeText": "To allow ACME, Inc. to store your email address",
"status": "accepted",
"subject": "JohnDoe",
"updatedDate": "2018-03-26T18:43:28.616Z"
}
]
},
"_links": {
"self": {
"href": "https://<server>/consent/v1/consents?subject=JohnDoe"
}
},
"count": 1,
"size": 1
}
You can fine-tune the search by adding another supported query parameter to the request. The GET /consents?param1={value}¶m2={value}
operation returns consent records that satisfy the filtering expression.
curl -X GET "https://<server>/consent/v1/consents?subject=JohnDoe&audience=salesforce.com" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"
The response data lists the consent records associated with John Doe (subject
) that apply to a specific audience
(salesforce.com).
Consent record validation rules
The Consents API performs basic validation on consent record create and modify operations, with many of the validation rules based on the value of the consent record status
attribute.
The following read-only attributes are set by the server and cannot be changed:
id
subjectDN
actorDN
createdDate
updatedDate
The following attributes are immutable; they cannot be changed after they are set:
subject
audience
definition
For all status
values, the definition ID must always be present.
If the status is accepted
or denied
, the definition must refer to an existing localization (definition.version
and definition.locale
). However, a consent record can be changed to the revoked
or restricted
status even if the originally accepted version no longer exists.
If the status is not pending
, then the consent record must contain subject
, actor
, audience
, titleText
, dataText
, and dataPurpose
attribute values. These attributes are not required for pending
consents because the user has not yet been prompted for consent, and the user ID might not be known.
For create operations, the status
attribute value cannot be set to revoked
or restricted
.
For modify operations, the status
attribute value cannot be changed to pending
.
In addition, the status
attribute value can be changed to revoked
or restricted
from the accepted
state only.
Add a consent record
You can create consent records to store responses from users. The request body requires values for the subject
, actor
, audience
, and status
attributes.
The subject
and actor
attributes do not have to be specified in the request because they are inferred from the authentication context by default. For unprivileged requesters, this is always the case; these fields are ignored if set by the client. Privileged requesters can set these values.
Note: The actor
attribute value is always inferred from the authentication context when an unprivileged client updates a consent record. However, a privileged client can provide an explicit value for the actor
attribute. The subject
attribute value is immutable and cannot be changed after the create operation.
The value for the status
attribute indicates how data represented by the consent record can be processed. The status
attribute supports the following options:
Status | Description |
---|---|
pending |
The consent record has been created but is not yet associated with a consent decision. This is a special-purpose state that exists to support Open Banking clients, which use this state to stage account requests prior to their approval. |
accepted |
The actor has granted consent for data to be shared with or processed by the audience. This is the only state that indicates that data may be shared or processed. |
denied |
The actor has declined consent. |
revoked |
The actor has revoked a previously accepted consent. This value cannot be set in a POST request. |
restricted |
An actor has previously accepted consent but has invoked the right to temporarily restrict processing of the data. For example, this status can be used when the user has entered into a dispute with the data processor. This value cannot be set in a POST request. |
In addition, the following consent definition resource properties must be provided:
-
id
The consent definition resource ID associated with this consent record.
-
version
The version number of the consent definition resource associated with this consent record.
-
locale
The consent definition resource’s localization locale used when recording this consent record.
The following consent definition resource properties must be provided when the status
resource property value is accepted
or denied
:
-
dataText
The description of the data to be collected, processed, or shared that is presented to the individual when requesting consent.
-
purposeText
The description of the reason for data access that is presented to the individual when requesting consent.
-
titleText
The title of the consent message that is presented to the individual when requesting consent.
Note: You can also define additional properties to store custom data that is relevant to the consent request.
The following sample shows the POST /consents/
operation to create a new consent record.
curl -X POST "https://<server>/consent/v1/consents" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
"status": "accepted",
"subject": "JohnDoe",
"actor": "JohnDoe",
"audience": "Apple",
"definition": {
"id": "share-my-email", \
"version": "1.0\",
"locale": "en-US" },
"dataText": "You agree to share this data...",
"purposeText": "This data will be used for..."
"titleText": "Share Your Data!"
}"
In this sample, the request body specifies values for all the attributes required to create the consent record. The status
attribute value is accepted
, which then requires values in the request body for the dataText
and purposeText
attributes.
If successful, the operation returns a 201: Success
message and shows the consent record data.
Update a consent record
There are two ways to modify an existing consent record. The PUT /consents/{id}
operation updates all attribute values for the identified record. In the request body, you must specify values for all required consent record attributes, including values for dataText
and purposeText
if the status
is modified from pending
to accepted
.
The PATCH /consents/{id}
operation performs a partial update operation, changing only the attribute values that you specify in the request body. Again, you must specify values for dataText
and purposeText
if the status
is modified from pending
to accepted
.
For example, you can use the PATCH /consents/{consentRecordId}
operation to update only a single attribute value on an identified consent record.
curl -X PATCH "https://<server>/v1/consents/{consentRecordId}" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
"status": "revoked"
}"
If successful, the operation returns a 200: Success
message and shows the updated consent record data.