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.

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 to the Authorization header. The bearer token is accepted per RFC 6750.

GET /consent/v1/definitions/cats?expand=localizations HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtp...

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.

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.

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 jwtToken" \
-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 multiple collaborators values, include the collaborator 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 jwtToken"

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}&param2={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 jwtToken"

The response data lists the consent records associated with John Doe (subject) that apply to a specific audience (salesforce.com).

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 operations

  A request that returns a body also returns the code 200 OK with the resource in the body of the response.

• POST operations

  A request that creates a new resource returns 201 CREATED with a Location header containing the location of the created resource.

• PUT or PATCH operations

  A request that updates a resource returns 200 OK and the full resource in the body.

• DELETE operations

  A 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 link

  Definition resources include a localizations link object that contains zero or more child localization resources. Consent resources (consent records) include a single localizations 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](#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 as displayName).

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"
}

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 sample shows the API request header (-H 'Authorization: Bearer) with a base64url-encoded bearer token as its parameter value.

curl -X "GET" "https://<server>/consent/v1/definitions" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

This request header also shows an additional parameter of note:

• Content-Type

  In the header of a PUT or POST request, this parameter identifies the media type of the request data sent to the server. For most Consent API calls, the Content-Type is application/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 jwtToken"

In the request header, the Bearer jwtToken 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,
}

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:

1. Create the account request: A makes a POST request to the /account-requests service on the data governance server at Company B. This POST specifies the list of permissions that Company A needs to be granted through the consent request.

2. Create a consent record: B makes a POST request to /consents on its directory server to create a consent record with the consent status value set to pending.

3. 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.

4. 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 a GET request to the /definitions/<consentDefinitionName>/localizations service for the specified consent definition.

5. 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.

curl -X POST "https://api.companyb.com/v1/account-requests" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer jwtToken" \
-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 jwtToken" \
-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 jwtToken"

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 jwtToken"

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 jwtToken" \
-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 jwtToken" \
-d "{
  "status": "revoked"
  }
}"