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

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