PingDirectory Consent API Reference
Before you read the Consent API topics or use the Consent API, review the following topics:
In addition, ensure you are familiar with HTTP headers, methods, and response codes. For more information, see the following articles:
Consent API Overview
What is the Consent API?
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.
Consent API model
The Consent API includes the following entities.
Definitions
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.
Localizations
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.
Consents
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.
Media types
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.
HAL properties
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
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.
Consent API Requests
Authentication
Authenticate Consent API requests with either user credentials (basic authentication) or an OAuth 2.0 access (bearer) token.
Basic authentication
Add encoded user credentials (user name/password) to the Authorization
header. You can either hard-code user credentials or programmatically obtain them.
GET /consent/v1/definitions/cats?expand=localizations HTTP/1.1
Authorization: Basic dWlkPXVzZXIuMCxvdT1wZW9...
If you use basic authentication, the Consent Service maps the username to a user distinguished name (DN) in the directory. A DN is a unique identifier. The Consent Service then uses this DN, called the request DN or auth DN, to determine whether the client should be considered privileged or unprivileged. The privileged or unprivileged identity is used to determine authorization.
Bearer token
Add a bearer token, shown here as accessToken
, to the Authorization
header. The bearer token is accepted per RFC 6750.
GET /consent/v1/definitions/cats?expand=localizations HTTP/1.1
Authorization: Bearer accessToken
Obtain the bearer token through an OAuth 2 authorization server, such as PingFederate. The bearer token must include a scope that defines what the requestor can access. The Consent Service must be configured to accept this scope. Additionally, the Consent Service can be configured to require that the bearer token include a specific audience claim. For more information about Consent Service configuration, see General Consent Service.
If you use a bearer token, the Consent Service maps the token’s subject claim to a user distinguished name (DN) in the directory. This DN is called the request DN or auth DN. The Consent Service then checks the scopes contained in the bearer token to determine whether the client should be considered privileged or unprivileged. The privileged or unprivileged identity is used to determine authorization.
Authorization
After authentication, the client's privileged or unprivileged identity determines level of access to the Consent Service.
-
Privileged
The requester can create, search, read, modify, or delete any consent record. A privileged requester is typically an administrator or an application service account, therefore it is not expected to match the subject or actor of the consent.
-
Unprivileged
The requester can only create, search, read, or modify consent records where the authenticated DN matches the DN of the consent record’s subject. An unprivileged requester is always assumed to be the subject or an agent acting directly on the subject’s behalf.
The privileged versus unprivileged identity types are used to prevent individuals from acting against any consent record but their own. It is important to note that how these identity types are configured determines the types of operations that the requester can perform. The following table summarizes common operations associated with identity types.
Operation | Notes |
---|---|
Read, search, create, modify, and delete any consent record. | Requester must be privileged. |
Operate against a consent record whose subject or actor cannot be mapped to a DN. | Requester must be privileged. |
Set an actor value that differs from the subject value. | Requester must be privileged. |
Create, read, search, or modify one's own consent records. | Requester can be unprivileged. |
Note: The Consent Service does not have the ability to determine the relationships between different subjects and actors.
Consent Body Attributes
Set the following consent attributes within the body.
status (string)
The consent status.
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. Possible values are as follows.
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. This value can be set in a POST request only. You cannot change status to pending in a PUT or PATCH request. |
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. You can change status to revoked from accepted only. |
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. You can change status to restricted from accepted only. |
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.
Required value with POST /consents
and PUT /consents/{{consentRecordId}}
. You can change this value, but it cannot be set to null.
subject (string)
The consent authorizes the audience to collect or share this individual or entity's data. This value is usually an arbitrary ID provided by an authorization server.
The subject
attribute does not have to be specified in the request because it is inferred from the authentication context by default. For unprivileged requesters, this is always the case; this field is ignored if set by the client. Privileged requesters can set this value.
This value is immutable. You cannot change it after you initially set it.
actor (string)
This individual or entity grants or denies the consent request. This value is usually an arbitrary ID provided by an authorization server.
The actor
attribute does not have to be specified in the request because it is inferred from the authentication context by default. For unprivileged requesters, this is always the case; this field is ignored if set by the client. Privileged requesters can set this value.
audience (string)
This entity requests or receives access to the subject's data. Typically, the client will supply an ID for itself as this value.
If status
is not pending
, this value is required. This attribute is not required for pending
consents because the user has not yet been prompted for consent, and the user ID might not be known.
This value is immutable. You cannot change it after you initially set it.
collaborators (array of strings)
After the consent grant, the audience shares the subject's data with these individuals. To account for multiple collaborators, there is no limit to how many values you can include in the array.
If collaborators
is set during an update, the new values will replace any existing values. The new values are not appended to the old values.
Optional value with create and modify operations. To clear this value, set it to null.
definition (object)
An object containing information about the associated definition.
Required object with POST /consents
and PUT /consents/{{consentRecordId}}
This value is immutable. You cannot change it after you initially set it.
definition.id (string)
The ID of the definition associated with this consent.
Required value with POST /consents
and PUT /consents/{{consentRecordId}}
This value is immutable. You cannot change it after you initially set it.
definition.version
The localization version associated with this consent.
Required value with POST /consents
and PUT /consents/{{consentRecordId}}
This value is immutable. You cannot change it after you initially set it.
definition.locale
The localization locale associated with this consent (for example, "en-US").
Required value with POST /consents
and PUT /consents/{{consentRecordId}}
This value is immutable. You cannot change it after you initially set it.
titleText (string)
The title of the consent request message.
If status
is not pending
, this value is required. This attribute is not required for pending
consents because the user has not yet been prompted for consent, and the user ID might not be known.
dataText (string)
A description of the data to be shared. This text is presented to the actor with the consent request.
If status
is not pending
, this value is required. This attribute is not required for pending
consents because the user has not yet been prompted for consent, and the user ID might not be known.
purposeText (string)
A description of the purpose for data access. This text is presented to the actor with the consent request.
If status
is not pending
, this value is required. This attribute is not required for pending
consents because the user has not yet been prompted for consent, and the user ID might not be known.
data (object)
An object containing arbitrary data that the client needs to store with the consent record. The Consent Service does not dictate the structure of this data in any way.
This object may include parameter values for fine-grained consents.
Optional value with create and modify operations.
consentContext (object)
An object containing arbitrary context information about the consent capture event. The Consent Service does not dictate the structure of this data in any way.
Examples of data that a client may wish to include in this object include a session ID, IP address, or location data.
Optional value with create and modify operations.
The following read-only attributes are set by the server and cannot be changed.
id (string, read-only)
The ID of the consent.
subjectDN (string, read-only)
The LDAP distinguished name (DN) corresponding to the subject. This DN allows a consent subject to be correlated to an LDAP user entry.
This property is set by the server only if the Consent Service is configured to do so.
actorDN (string, read-only)
The LDAP distinguished name (DN) corresponding to the actor. This DN allows a consent actor to be correlated to an LDAP user entry.
This property is set by the server only if the Consent Service is configured to do so.
createdDate (string, read-only)
The date and time when the consent record was created, in ISO-8601 format.
updatedDate (string, read-only)
The date and time when the consent record was last modified, in ISO-8601 format.
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 accessToken" \
-d "{
"status": "accepted",
"subject": "JohnDoe",
"actor": "JohnDoe",
"audience": "Apple",
"collaborators": ["Alice","Bob"],
"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.
Query parameters
Link expansion
Supported Endpoints
-
GET /consents/{{consentRecordId}}
-
GET /definitions/{{definitionId}}
-
GET /definitions/{{definitionId}}/localizations/{{localizationId}}
You can optimize the information returned by a request through link expansion. Link expansion is helpful when you need the query to return detailed information from an additional resource in the response data. You can identify a resource to expand using the expand
query string parameter in the request. The allowed values for the expand
parameter are found in a resource's _links
field (not including "self"). The Consent API supports link expansion for the localizations
resource only.
Here is a sample request that does not use the expand
parameter.
GET /definitions/share-email
The response data looks like this:
{
{
"_links": {
"localizations": [
{
"href": "https://<server>/consent/v1/definitions/share-email/localizations/en-US",
"hreflang": "en-US"
}
],
"self": {
"href": "https://<server>/consent/v1/definitions/share-email"
}
},
"displayName": "Share Email!",
"id": "share-email",
"parameters": [
"param1"
]
}
When using the expand
parameter in the request (GET /definitions/share-email?expand=localizations
), the returned data for the share-email
resource looks like this:
{
"_embedded": {
"localizations": [
{
"dataText": "Can we share your email address with our partners?",
"id": "en-US",
"locale": "en-US",
"purposeText": "Receive email offers from our partners.",
"titleText": "Receive Email Offers",
"version": "1.0"
}
]
},
"_links": {
"localizations": [
{
"href": "https://<server>/consent/v1/definitions/share-email/localizations/en-US",
"hreflang": "en-US"
}
],
"self": {
"href": "https://<server>/consent/v1/definitions/share-email"
}
},
"displayName": "Share Email!",
"id": "share-email",
"parameters": [
"param1"
]
}
Note: If available, you can specify multiple resources to expand in the query string by listing multiple attribute names separated by commas.
Filtering definitions and localizations
Supported Endpoints
-
GET /definitions
-
GET /definitions/{{definitionId}}/localizations
Requests that are known to return a large number of items can be filtered using the filter
query string parameter. The following SCIM protocol filtering operators are supported.
-
co
(contains)The entire operator value must be a substring of the attribute value.
Supported attributes:
displayName
,description
,locale
,version
,dataText
,purposeText
,titleText
,id
,localizations.id
-
sw
(starts with)The entire operator value must be a substring of the attribute value. The substring must start at the beginning of the attribute value.
Supported attributes:
displayName
,description
,locale
,version
,dataText
,purposeText
,titleText
,id
,localizations.id
-
eq
(equals)The attribute and operator values must be identical.
Supported attributes:
displayName
,description
,locale
,version
,dataText
,purposeText
,titleText
,id
,localizations.id
-
in
(includes)The entire operator value must be a substring of the attribute value.
Supported attributes:
displayName
,description
,locale
,version
,dataText
,purposeText
,titleText
,id
,localizations.id
-
ew
(ends with)The entire operator value must be a substring of the attribute value. The substring must end at the end of the attribute value.
Supported attributes:
displayName
,description
,locale
,version
,dataText
,purposeText
,titleText
,id
,localizations.id
-
gt
(greater than)The attribute value must be greater than the operator value. Since
version
is a string, this is a lexicographical comparison.Supported attributes:
version
-
lt
(less than)The attribute value must be less than the operator value. Since
version
is a string, this is a lexicographical comparison.Supported attributes:
version
-
ge
(greater than or equal to)The attribute value must be greater than or equal to the operator value. Since
version
is a string, this is a lexicographical comparison.Supported attributes:
version
-
le
(less than or equal to)The attribute value must be less than or equal to the operator value. Since
version
is a string, this is a lexicographical comparison.Supported attributes:
version
-
ne
(not equal)The attribute and operator values are not identical.
Supported attributes:
version
-
pr
(present/has value)The attribute has a non-empty or non-null value.
Supported attributes: All non-HAL attributes
-
and
(logical AND)Logical AND for building compound expressions where both expressions are true.
-
or
(logical OR)Logical OR for building compound expressions if either expression is true.
-
not
(logical NOT)Logical NOT for building compound expressions if the expression evaluates to false.
For example, here is a sample SCIM filtering expression that returns the localization resources where the locale starts with en
and the data text contains the word email
:
https://<server>/consent/v1/definitions/{{definitionId}}/localizations?filter=locale sw "en" and dataText co "email"
Here is the same filter with URL encoding to account for spaces (%20) and quotation marks (%22):
https://<server>/consent/v1/environments/{{envID}}/users?filter=locale%20sw%20%22en%22%20and%20dataText%20co%20%22email%22"
For more information about the SCIM Protocol Specification, see SCIM Filtering.
Filtering consents
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.
-
collaborator
The consent is shared with this individual.
Note The filter attribute,
collaborator
, is singular, but the body attribute,collaborators
, is plural. Also,collaborator
searches can only be performed successfully if the requester is privileged. For more information about privileged and unprivileged requests, see the "Authorization" section of this topic. In addition, if you need to filter for multiplecollaborators
values, include thecollaborator
filter multiple times in your filter expression, as shown in the following sample.
The following sample shows the GET /consents
operation to return the consent records associated with the specified subject and collaborators.
curl -X GET "https://<server>/consent/v1/consents/?subject=JohnDoe&collaborator=Alice&collaborator=Bob" \
-H "Content-type: application/json" \
-H "Authorization: Bearer accessToken"
The response data shows all consent records associated with subject
John Doe, collaborator
Alice, and collaborator
Bob:
{
"_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/5caa81af-ec05-41ff-a709-c7378007a99c"
}
},
"actor": "JohnDoe",
"audience": "client1",
"collaborators": ["Alice","Bob"],
"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": "5caa81af-ec05-41ff-a709-c7378007a99c",
"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&collaborator=Alice&collaborator=Bob"&audience=salesforce.com" \
-H "Content-type: application/json" \
-H "Authorization: Bearer accessToken"
The response data lists the consent records associated with John Doe (subject
) that apply to a specific audience
(salesforce.com).
Consent API Responses
HTTP response headers
The Consent API includes information about the result of the operation in the HTTP headers. This enables you to determine the appropriate action to take without having to parse the response body.
The following HTTP Headers are returned by every operation:
-
Access-Control-Allow-Headers
This header is used in response to a preflight request to indicate that HTTP headers can be used when making a request.
-
Access-Control-Allow-Max-Age
This header specifies how long the results of a preflight request can be cached.
-
Access-Control-Allow-Methods
This header specifies specifies the method or methods allowed when accessing the resource in response to a preflight request.
-
Content-Type
This header specifies the data exchange format for the result data. This value should be
application/HAL+json
. -
Date
This header specifies the date the response was sent.
HTTP response codes
The Consent API returns the status of an operation as a registered HTTP response code. The HTTP response codes are:
-
200-299
Confirms a successful call.
-
300-399
Indicates that the call or subsequent calls should be made to another resource.
-
400-499
Shows that an exception occurred, generally due to client code, insufficient permissions, or incorrect parameters.
-
500-599
Shows that an error occurred, generally due to an issue with the service (for example, a service outage).
Operations may also return additional information about a failed operation in the HTTP response body.
For more information on HTTP response codes, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
Synchronous responses
Responses for synchronous operations have the following behavior:
-
GET
operationsA request that returns a body also returns the code
200 OK
with the resource in the body of the response. -
POST
operationsA request that creates a new resource returns
201 CREATED
with aLocation
header containing the location of the created resource. -
PUT
orPATCH
operationsA request that updates a resource returns
200 OK
and the full resource in the body. -
DELETE
operationsA request that deletes a resource returns
204 NO CONTENT
.
Response data structure
All Consent API resources return data using the HAL+JSON content type. The HAL media type provides a common format for linking API resources. HAL conventions adopted by the Consent APIs result in an easily readable structure for resource links and for expressing embedded resources contained within parent resources. The following sample shows how embedded resources are structured in the response data.
{
"count": 3,
"size": 3,
"_links": {
"self": {
"href": "https://<server>/consent/v1/definitions"
}
},
"_embedded": {
"definitions": [
{
"id": "5caa81af-ec05-41ff-a709-c7378007a99c",
"name": "Defn 1 name",
"description": "Defn1 description",
}
...
}
}
For collections, the result data returns a count
and size
attribute, and all API requests return a self
URL under the _links
attribute that identifies the URI of the main resource.
The _embedded
attribute lists all the results in the collection. In the sample above, the count
attributes tells you that there are three definitions
in the collection.
Relationships, links, and references
Relationships between resources or operations can be described as follows:
-
self
link.All resources return a
self
link in the response body. -
localizations
linkDefinition resources include a
localizations
link object that contains zero or more child localization resources. Consent resources (consent records) include a singlelocalizations
link object. -
parent
link.Localization resources include a
parent
link object that contains a single parent definition resource. -
definitions
Consent resources (consent records) include a
definitions
link object that contains a single definition resource.
These relationships and references are represented as follows:
-
Links are represented using JSON HAL conventions (such as, in a
_links
object). -
Links are represented as absolute URLs.
-
Links can be expanded using the
expand
parameter. See Link expansion. The links can also be referenced via the "property-as-resource" pattern. -
References as attributes have an
id
value and may also have additional attributes (such asdisplayName
).
Errors
Errors generated by the Consent API are intended to allow you to resolve specific errors programmatically. An error response consists of a high-level error code that must be handled by the client and optional details containing specific information on how to resolve the fault. The Consent API errors return a response payload formatted as follows:
{
"id": "454",
"code": "INVALID_DATA",
"message": "Unable to parse request: Can not construct instance of com.unboundid.directory.server.extensions.consent.types.ConsentStatus from String value (\"foo\"): value not one of declared Enum instance names: [restricted, revoked, pending, denied, accepted] at line: -1, column: -1"
}
Attribute | Required | Description |
---|---|---|
id |
Yes | A unique identifier that is stored in log files and always included in an error response. This value can be used to track the error received by the client (with server-side activity included for troubleshooting purposes). |
code |
Yes | A general fault code which the client must handle to provide all exception handling routines and to localize messages for users. This code is common across all services and is human readable (such as a defined constant rather than a number). |
message |
Yes | A short description of the error. This message is intended to assist with debugging and is returned in English only. |
Consent API Getting started
The following information illustrates how to construct a typical Consent API request.
Create the API request header
The API request header contains the authentication information you must provide to make a call to any Consent API resource. The Authorization
parameter takes the user credentials or the full bearer token as its value, which contains the authorization information needed to access the requested resource.
The following samples show the API request header (-H 'Authorization: Bearer
) where accessToken
is a base64url-encoded bearer token.
curl -X "GET" "https://<server>/consent/v1/definitions" \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer accessToken'
This request header also shows an additional parameter of note:
-
Content-Type
In the header of a
PUT
orPOST
request, this parameter identifies the media type of the request data sent to the server. For most Consent API calls, the Content-Type isapplication/json
.
Create the API request body
The API request body for POST
, PATCH
, or PUT
requests provides the attribute values needed to complete the create or update operation. For example, to update a consent record, the PUT
operation requires values for the attr1
and attr2
attributes in the request body:
{
"attr1": "value1",
"attr2": "value2"
}
Submit the API request
You can use the Consent API to return a list of consent definitions.
The following sample shows the GET /definitions
operation to return a list of all consent definitions and their attributes.
curl -X GET "https://<server>/consent/v1/definitions" \
-H "Content-type: application/json" \
-H "Authorization: Bearer accessToken"
In the request header, the Bearer accessToken
value is your full base64url-encoded token generated by the authentication service. If your token is valid, the API request returns a 200: Successful operation
message, and the response data lists all consent definitions.
This GET
request does not require a request body.
Evaluate the response
The response returns the list of consent definitions.
{
"_links": {
"self": {
"href": "https://<server>/consent/v1/definitions"
}
},
"_embedded": {
"definitions": [
{
"id": "share-my-email",
"displayName": "ShareEmail"
"_links": {
"self": {
"href": "https://<server>/consent/v1/definitions/share-my-email"
}
}
}
]
}
"size": 1,
"count": 1,
}
Consent API Activity
Introduction
The Consent API may be used as the data backend for an Open Banking account requests API. For more information about Open Banking, see Open Banking.
In this activity, a third-party payment processor (Company A) makes an account request to an account servicing provider (Company B) on behalf of the account holder (Customer). Company A needs permission to access specific account data. To move forward with the transaction, a consent request must be sent to the Customer, and a consent record must be created to capture the consent response.
This scenario illustrates some common open banking operations supported by the Consent API, including:
- Creating a consent record.
- Checking the state of an existing consent record.
- Retrieving localized consent prompt text.
- Updating a consent record.
The actors in this scenario are:
-
The Customer
This is the account holder who must provide consent so that the third party can access account data.
-
Third-Party Provider (Company A)
This is the third-party client that requires access to the customer’s account data.
-
Account Servicing Payment Servicing Provider (Company B)
This is the service that processes the customer’s accounts and consents. This service consists of:
- A data governance server, which provides the Open Banking account requests API.
- A PingFederate server, which handles OpenID Connect authentication and OAuth2 authorization in conjunction with a Consent Capture Web Application.
- A directory server, which provides the Consent Service and the Consent Capture Web Application.
Workflow order of operations
To request the Customer's consent, the following tasks must be completed successfully:
-
Create the account request: A makes a
POST
request to the/account-requests
service on the data governance server at Company B. ThisPOST
specifies the list of permissions that Company A needs to be granted through the consent request. -
Create a consent record: B makes a
POST
request to/consents
on its directory server to create a consent record with the consentstatus
value set topending
. -
Check the account request state: Using the consent record id generated in step 2, Company A can now make a GET request to Company B's consent capture app to check the account request state to see if the Customer has accepted or denied consent.
-
Prompt to get the Customer's consent: If the consent state is
pending
, the consent capture app prompts the Customer to grant authorization. The app makes aGET
request to the/definitions/<consentDefinitionName>/localizations
service for the specified consent definition. -
Update the consent record: The Customer grants or denies authorization, and the consent capture app makes a
PATCH
request to/consents
to update the consent record based on the Customer's response.
Create the account request
Company A needs the following common open banking permissions from the Customer:
- ReadAccountsDetail
- ReadBalances
- ReadBeneficiariesDetail
- ReadDirectDebits
- ReadProducts
Company A knows that Company B has a standard consent definition called OpenBankingAccountsConsent that can be used to capture consent from the Customer for these permissions.
The POST /account-requests
operation initiates the consent request. The request body specifies these permissions. In the Authorization request header field, the accessToken
value is your full base64url-encoded JSON web token generated by the authentication service.
curl -X POST "https://api.companyb.com/v1/account-requests" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken" \
-d "{
"data": {
"permissions": [
"ReadAccountsDetail",
"ReadBalances",
"ReadBeneficiariesDetail",
"ReadDirectDebits",
"ReadProducts"
]
}
}"
The response data shows the requested permissions as well as the AccountRequestId
and the status
of the account request.
Create a consent record
Company B creates a consent record to capture and store the Customer's response to the consent request on its directory server. The request body must provide values for the status
, subject
, actor
, and audience
properties. In this case, the status
property value is set to pending
. In addition, the request can define additional properties to store custom data relevant to the consent request, such as the permissions requested by Company A.
The POST /consents/
operation creates a new consent record.
curl -X POST "https://api.companyb.com/consent/v1/consents" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken" \
-d "{
"status": "pending",
"subject": "Customer",
"actor": "Customer",
"audience": "CompanyA",
"definition": {
"id": "OpenBankingAccountsConsent", \
"version": "1.0\",
"locale": "en-US" },
"data": {
"Permissions": [
"ReadAccountsDetail", \
"ReadBalances", \
"ReadBeneficiariesDetail", \
"ReadDirectDebits", \
"ReadProducts"
]
}
}"
If successful, the operation returns a 201: Success
message and shows the consent record data. The consent record id
and other properties shown in the consent record data can be converted into an open banking response sent to Company A for further action. The consent record data looks like this:
{
"_links": {},
"_embedded": {},
"status": "pending",
"subject": "Customer",
"actor": "Customer",
"audience": "CompanyA",
"definition": {
"id": "OpenBankingAccountsConsent",
"version": "1.0",
"locale": "en-US"
},
"id": "4308ac1d-a493-426d-9211-224255145d28",
"dataText": "Allow access to your financial accounts.",
"purposeText": "This data is required to complete your transaction.",
"data": {
"Permissions": [
"ReadAccountsDetail", \
"ReadBalances", \
"ReadBeneficiariesDetail", \
"ReadDirectDebits", \
"ReadProducts"
]
},
"consentContext": {}
}
Check the account request state
Company A checks the consent status of the Customer's account. It makes a GET
request to the /account-requests/{{AccountRequestId}}
service on the data governance server at Company B using the AccountRequestId
property value returned in Create the account request. Company B checks the consent status by making a GET
request to the /consents/{{consentRecordId}}
service on its directory server.
The GET /consents/{{consentRecordId}}
operation finds the consent record data for the consentRecordId
returned in Create a consent record.
curl -X GET "https://api.companyb.com/consent/v1/consents/5caa81af-ec05-41ff-a709-c7378007a99c" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken"
In this case, the resulting consent record data shows the status
property as pending
, which tells company A that it needs to move forward by prompting the Customer to grant authorization.
{
...
"status": "pending",
"subject": "Customer",
"actor": "Customer",
"audience": "CompanyA",
...
}
Prompt to get the Customer's consent
Company B gets the consent definition's localized text to display a consent prompt to the Customer. The consent capture app makes a GET
request to the /definitions/{{definitionId}}/localizations
service on the directory server.
The GET definitions/OpenBankingAccountsConsent/localizations
operation gets the consent record data for the OpenBankingAccountsConsent
consent definition.
curl -X GET "https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent/localizations" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken"
The response data shows the current consent definition localizations. For this consent definition, there are two localizations resources: en-US
and fr-CA
.
{
"count": 2,
"size": 2,
"_links":{
"self":{
"href":"https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent/localizations"
}
},
"_embedded":{
"localizations":[
{
"_links":{
"parent":{
"href":"https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent"
},
"self":{
"href":"https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent/localizations/en-US"
}
},
"id":"en-US",
"locale":"en-US",
"version":"1.1",
"dataText":"Allow access to your financial accounts.",
"purposeText":"This data is required to complete your transaction."
},
{
"_links":{
"parent":{
"href":"https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent"
},
"self":{
"href":"https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent/localizations/fr-CA"
}
},
"id":"fr-CA",
"locale":"fr-CA",
"version":"1.2",
"dataText":"Autoriser l'accès à vos comptes financiers.",
"purposeText":"Ces données sont nécessaires pour compléter votre transaction."
}
]
}
}
Update the consent record
After the Customer responds to the consent prompt, the authorization or denial of consent is added to the consent record. The consent capture app makes a PATCH
request to the /consents/{{consentRecordId}}
service to update the Customer's consent record. The updated record stores the information collected by the consent capture app from the Customer's response to the consent prompt.
The PATCH /consents/{{consentRecordId}}
operation updates an existing consent record, modifying the record to reflect only the new property values specified in the request body. The consentRecordId
value obtained in Create a consent record is added to the request URL to identify the Customer's consent record.
curl -X PATCH "https://api.companyb.com/consent/v1/consents/5caa81af-ec05-41ff-a709-c7378007a99c" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken" \
-d "{
"status": "accepted"
}
}"
In this sample, the Customer is prompted to ALLOW/DENY authorization to Company A for all data-sharing permissions. The request body specifies a modification to only the status
property value to reflect the Customer's response. The updated consent record looks like this:
{
"_links": {},
"_embedded": {},
"status": "accepted",
"subject": "Customer",
"actor": "Customer",
"audience": "CompanyA",
"definition": {
"id": "OpenBankingAccountsConsent",
"version": "1.0",
"locale": "en-US"
},
"id": "32adc1d-a493-426d-9211-224255145d28",
"dataText": "Allow access to your financial accounts.",
"purposeText": "This data is required to complete your transaction.",
"data": {
"Permissions": [
"ReadAccountsDetail", \
"ReadBalances", \
"ReadBeneficiariesDetail", \
"ReadDirectDebits", \
"ReadProducts"
]
},
"consentContext": {}
}
If the Customer chooses to terminate the relationship with Company A, the Customer can revoke consent. In this case, to honor the Customer's revocation request, Company A makes a DELETE
request to the /account-requests/{{AccountRequestId}}
service on Company B's data governance server. To complete the operation, Company B makes a PATCH
request to the /consent/v1/consents/{{consentRecordId}}
service on the directory server, specifying the change in status
for the account.
curl -X PATCH "https://api.companyb.com/consent/v1/consents/5caa81af-ec05-41ff-a709-c7378007a99c" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken" \
-d "{
"status": "revoked"
}
}"