Manage consent definitions and localizations


Definitions and localizations

A definition resource describes the type of data that warrants consent and the purpose for collecting or sharing that data. The consent service implements functions to search for and list consent definitions. It also supports operations to find and view the localizations resources associated with each stored consent definition.

The localizations resources associated with a consent definition contains the version-specific, language-specific prompt and data text for the consent Definition presented to users. For example, if a consent request to Canadian users must be presented in English and French, then the consent Definition needs two Localizations entities to specify BCP 47 compliant language tag for the locales: en-CA and fr-CA. For more information about BCP 47 tags for identifying languages, see BCP 47.

Note: The consent definition API is read-only. Consent definitions and localizations are created out-of-band using the Directory Server’s standard configuration facilities. Any authenticated client may search and read all consent definitions and localizations.

Filtering result data

GET requests for consent definitions supports SCIM filtering expressions. Filters can be appended to the request URL to fine-tune the response data. For example, this filter returns only the definitions resources in which the displayName attribute value starts with the letter “S”:

https://<server>/v1/definitions?filter=displayName%20sw%20%22S%22

These SCIM operators can be applied to the following attributes:

  • co (contains)

    Supported attributes: displayName, description, locale, version, dataText, purposeText, id, localizations.id

  • sw (starts with)

    Supported attributes: displayName, description, locale, version, dataText, purposeText, id, localizations.id

  • eq (equals)

    Supported attributes: displayName, description, locale, version, dataText, purposeText, id, localizations.id

  • in (includes)

    Supported attributes: displayName, description, locale, version, dataText, purposeText, id, localizations.id

  • ew (ends with)

    Supported attributes: displayName, description, locale, version, dataText, purposeText, id, localizations.id

  • gt (greater than)

    Supported attributes: version

  • lt (less than)

    Supported attributes: version

  • ge (greater than or equal to)

    Supported attributes: version

  • le (less than or equal to)

    Supported attributes: version

  • ne (not equal)

    Supported attributes: version

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

Note: The pr (present, is a non-empty or non-null value) operator is supported for all non-HAL attributes. For more information about SCIM syntax and operators, see Conventions.

You can get all consent definition resources, a selected set of definition resources (using a filter), or a specific definition resource.

The following sample shows the GET /definitions operation to return all consent definitions.

curl -X GET "https://<server>/consent/v1/definitions" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data lists all consent definition resources:

{
  "size": 3,
  "count": 3,
  "_links": {
    "self": {
      "href": "https://<server>/v1/consent/v1/definitions"
    }
  },
  "_embedded": {
    "definitions": [
      {
        "id": "share-my-email",
        "displayName": "ShareEmail"
        "_links": {
          "self": {
            "href": "https://<server>/v1/consent/v1/definitions/share-my-email"
      },
      {
        "id": "share-my-data",
        "displayName": "ShareData",
        "_links": {
          "self": {
            "href": "https://<server>/v1/consent/v1/definitions/share-my-data"
          },
      {
        "id": "allow-remote-control",
        "displayName": "AllowRemoteControl",
        "_links": {
          "self": {
            "href": "https://<server>/v1/consent/v1/definitions/allow-remote-control"
          }  
        }
      }
    ]
  }
}

You can use a SCIM filter to return only the consent definition resources that satisfy the query filter parameters. See SCIM Filtering for reference.

The GET /definitions operation returns consent definition resources that have a displayName that starts with S.

curl -X GET "https://<server>/consent/v1/definitions?filter=displayName%20sw%20%22S%22" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The GET /definitions/{id} operation returns only the consent definition resource identified by its ID.

curl -X GET "https://<server>/consent/v1/definitions/share-my-data" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
  "id": "share-my-data",
  "displayName": "ShareData",
  "_links": {
    "self": {
      "href": "https://<server>/consent/v1/definitions/share-my-data"
    }
  }
}

Get localizations

You can get all localization resources associated with a consent definition, or you can get a specific localization entity for an identified consent definition resource.

The following sample shows the GET /definitions/{definitionId}/localizations operation to return all localizations resources associated with the specified definitions resource.

curl -X GET "https://<server>/v1/definitions/share-my-email/localizations" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data shows the collection of localization resources associated with the share-my-email consent definition resource.

{
  "size": 2,
  "count": 2,
  "_links": {
    "self": {
      "href": "https://<server>/consent/v1/definitions/share-my-email/localizations"
    }
  },
  "_embedded": {
    "localizations": [
      {
        "id": "en-US",
        "locale": "en-US",
        "version": "1.0",
        "dataText": "Share your email address with ACME, Inc.",
        "purposeText": "To share email"
        "_links": {
          "self": {
            "href": "https://<server>/consent/v1/definitions/share-my-email/en-US"
      },
      {
        "id": "en-CA",
        "locale": "en-CA",
        "version": "1.0",
        "dataText": "Share your email address with ACME, Inc.",
        "purposeText": "To share email"
        "_links": {
          "self": {
            "href": "https://<server>/consent/v1/definitions/share-my-email/en-CA"
          }
        }
      }
    ]
  }
}

The GET /definitions/{definitionId}/localizations/{localizationsId} operation returns only the localization resource (identified by its ID) for the specified consent definition resource.

curl -X GET "https://<server>/consent/v1/definitions/share-my-email/localizations/en-US" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

"_links": {
   "parent": {
     "href": "https://<server>/consent/v1/definitions/share-my-email"
   },
   "self": {
     "href": "https://<server>/consent/v1/definitions/share-my-email/localizations/en-US"
   }
 },
 "id": "en-US",
 "locale": "en-US",
 "version": "1.0",
 "dataText": "Share your email address with ACME, Inc.",
 "purposeText": "To share email"
}