Home

Consent Guide

The Signatu Consent API is a modern REST API. The API is compliant with the OpenAPI specification, ensuring that you can integrate a large number of technologies and use cases through standard tooling.

Schema

FieldTypeDescription
subjectURI or stringClaim for subject principal
issuerURI or stringClaim for issuer principal
targetURI or stringClaim for target of the consent - e.g., URL of a policy
sourceURI or stringClaim for source of the consent principal. If using the SDK this field will be automatically generated.
scopestringThe scope of the consent. Typically this will refer to a section or clause in the target. If not specified, it will be automatically set to default.
delegateURI or stringClaim for delegate principal acting on behalf of the subject principal - e.g, a customer care representative registering consent on behalf of the subject who has called on the phone
actionboolean or nullIf null, no action was taken. true: subject accepted, false: subject declined.
token (return value)stringToken representing this consent, suitable for exchange between humans. This field will be automatically generated.
createdAt (return value)ISO 8601 stringTime of creation. This field will be automatically generated.

Endpoint

The Consent API v0 is available at https://api.signatu.com/consent/v0

You can use any HTTP client to interact with the API, but in our examples we will use curl. You do need an access token to use the API - see Authorization.

Examples

Refer to the API Documentation for a detailed specification of the API.

GET /consents/{id}

Get the consent event specified by {id}.

GET /consents/{id}/receipt

Get the Consent Receipt for the event specified by {id}.

POST /consents

Create one or more new consent events. To create a single event, POST a single JSON document. To create multiple events, POST an array of events.

The events have write-once semantics, and cannot be changed after creation.

GET /consents/token/{id}

Return the consent event identified by the token {id}. This token is suitable to use in customer service scenarios where the customer refers to the token {id} e.g., over the phone.

Note that there is a low but theoretical possibility of false positives here, i.e., that multiple events have the same token {id}. Hence the token cannot be used to uniquely identify a consent event.

GET /consents/search

Search for events matching the specified filter criteria in the query string and return an array with results.

Query parameters

NameDescriptionRequired
subjectsubject URL or stringYes
issuerissuer URL or stringYes
targettarget URL or stringYes
sourcesource URL or stringNo
scopescope stringNo
currentboolean. If set to true only return the current consent event, i.e., chronologically newest. If scope is not defined, the current event for each scope will be returned.No

Example

$ curl 'https://api.signatu.com/consent/v0/consents/search?issuer=bar&target=baz&subject=foo' -H 'Authorization: Bearer xxxxxxxxxxxxxxx'
[{
"id": "e98399acee9018dc3b997d1f9783a637dac23f3c1c1cb4849f040ea18a7cc6ac",
"scope": "default",
"subject": "foo",
"issuer": "bar",
"target": "baz",
"action": true,
"token": "F5KLLW",
"createdAt": "2017-06-20T18:28:38.000Z"
},
{
"id": "1666a664380aad0d6d4ed0cb3357be28637b3a25a18b9b3f1c49501e7835d73e",
"scope": "default",
"subject": "foo",
"issuer": "bar",
"target": "baz",
"action": true,
"token": "NSHC17",
"createdAt": "2017-06-20T18:28:37.000Z"
}]

Statistics

GET /consents/statistics

Retrieve consent statistics for the application indentified by the Authorization.

The Consent Receipt is a JSON Web Token (JWT) corresponding to the Kantara Consent Receipt Specification v1.0.0. The receipt is signed using public key encryption, making the contents of the receipt tamper-proof.

See jwt.io for resources on how to work with JWT tokens.

Format

The data received from the API is an JSON object having the JWT token in receipt:

{
"receipt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzdHJpbmciLCJwb2xpY3lVcmwiOiJzdHJpbmciLCJpYXQiOjE0OTgwNDcwMzcsInB1YmxpY0tleSI6Imh0dHBzOi8vc2lnbmF0dS5jb20vY29uc2VudC9zaWduYXR1LWp3dC5wdWIiLCJkYXRhQ29udHJvbGxlciI6eyJvcmciOiJzdHJpbmcifSwiaXNzIjoiaHR0cHM6Ly9zaWduYXR1LmNvbS9jb25zZW50L2FwaS92MCIsImp0aSI6IjdQTU4zMSIsInNpZ25hdHUiOnsiY29uc2VudCI6eyJpZCI6ImI5ZWZjYmI0ZmY3NDkyNTFlYWUwY2I4NmQwYTAzMDc4ODE4NjFhZjcwNGZhZWNkMGYxMjNiNWJmZjE1YWExNzYiLCJzdWJqZWN0Ijoic3RyaW5nIiwiaXNzdWVyIjoic3RyaW5nIiwidGFyZ2V0Ijoic3RyaW5nIiwic291cmNlIjoic3RyaW5nIiwic2NvcGUiOiJzdHJpbmciLCJhY3Rpb24iOnRydWV9fX0.cldpXCDnmru4QDd7feb0seswzhW9SQQJCEG9smCYTB8WJh9DjcvBNd9mygVdORbdyVcHVWVnIgebqeq24SNiJxxbGHufuVFWI4AbXhKLANKc96F6erj81zhTqZEnwhuYexpQiEORUCrX2JmEFDFfcerFJSKpCHo_NAgoD5ztrLv8n4Tiv5QCRgm-yuH8YsGt3pNkRqRCe005TxNMRQnTd_DixEBvxdQa-sTU1YVv-byOYIS2_alHsUHwNAdqOYQg2eWezsS0h5EIxbv2jZG_oL9pw90A6JbOY6PGH4AqmQ38n69OkKAVqutTdPKAHFyAAdeZJdaVQHXrmKQAqyIW_Q"
}

Use cases

These examples don’t show the Authorization header - make sure to add that to a header.

For these examples, we use the following example data:

  • subject: foo@bar.com
  • issuer: https://foo.com
  • target: https://foo.com/policy/v12

To give a consent, simply POST the required data to /consents.

curl 'https://api.signatu.com/consent/v0/consents' -d 'subject=foo%40bar.com&issuer=https%3A%2F%2Ffoo.com&target=https%3A%2F%2Ffoo.com%2Fpolicy&source=https%3A%2F%2Ffoo.com%2Flogin&scope=personalization&action=true'
{
"id": "2faa1e62f4345e1e269ea1bc6a5894f478f7cb622473c3065f8591da0b4a0a1a",
"scope": "personalization",
"subject": "foo@bar.com",
"issuer": "https://foo.com",
"target": "https://foo.com/policy",
"source": "https://foo.com/login",
"action": true,
"token": "IUFBJT",
"createdAt": "2017-06-22T09:42:02.960Z"
}

Consents are immutable, so a withdrawal is simply a POST of with action: false, e.g.,

curl 'https://api.signatu.com/consent/v0/consents' -d 'subject=foo%40bar.com&issuer=https%3A%2F%2Ffoo.com&target=https%3A%2F%2Ffoo.com%2Fpolicy&source=https%3A%2F%2Ffoo.com%2Flogin&scope=personalization&action=false'
{
"id": "51a340268e7cd1d1d90a1f84f41a13b0a9e06bda8998ed6dd203318199fe2db3",
"scope": "personalization",
"subject": "foo@bar.com",
"issuer": "https://foo.com",
"target": "https://foo.com/policy",
"source": "https://foo.com/login",
"action": false,
"token": "AGBDUX",
"createdAt": "2017-06-22T09:43:49.340Z"
}

To list all current and prior consent events for a privacy policy for a subject:

$ curl 'https://api.signatu.com/consent/v0/consents/search?issuer=foo.com&target=https%3A%2F%2Ffoo.com%2Fpolicy&subject=torgeir%40signatu.com'
[
{
"id": "2242374e1394b7862d030c117cbc57df024f948f2e8dc53a3a63ef327e628d79",
"subject": "foo@bar.com",
"issuer": "https://foo.com",
"target": "https://foo.com/policy",
"source": "https://foo.com/login",
"scope": "marketing",
"action": false,
"token": "VR6BCF",
"createdAt": "2016-12-12T11:38:01.000Z"
},
{
"id": "5b04b1785aff59209c233a844a9f5713114dfe78fdf5b9ad893170fb92171767",
"subject": "foo@bar.com",
"issuer": "https://foo.com",
"target": "https://foo.com/policy/v12",
"source": "https://foo.com/login",
"scope": "marketing",
"action": true,
"token": "2IFHI2",
"createdAt": "2016-12-12T11:38:01.000Z"
},
{
"id": "501c04d1fc4e4f50b19320768abf44a27bb6ba418cc99276679026a25422b75a",
"scope": "default",
"subject": "foo@bar.com",
"issuer": "https://foo.com",
"target": "https://foo.com/policy/v12",
"source": "https://foo.com/login",
"action": true,
"token": "Y3Y27Q",
"createdAt": "2016-10-11T11:38:01.000Z"
}
]

Add the &current=true to the request above will return the current consent event for each scope.

$ curl 'https://api.signatu.com/consent/v0/consents/search?issuer=foo.com&target=https%3A%2F%2Ffoo.com%2Fpolicy&subject=orgeir%40signatu.com&current=true'
[
{
"id": "5b04b1785aff59209c233a844a9f5713114dfe78fdf5b9ad893170fb92171767",
"scope": "marketing",
"subject": "foo@bar.com",
"issuer": "https://foo.com",
"target": "https://foo.com/policy/v12",
"source": "https://foo.com/login",
"action": true,
"token": "2IFHI2",
"createdAt": "2016-12-12T11:38:01.000Z"
},
{
"id": "501c04d1fc4e4f50b19320768abf44a27bb6ba418cc99276679026a25422b75a",
"scope": "default",
"subject": "foo@bar.com",
"issuer": "https://foo.com",
"target": "https://foo.com/policy/v12",
"source": "https://foo.com/login",
"action": true,
"token": "Y3Y27Q",
"createdAt": "2016-10-11T11:38:01.000Z"
}
]

If both scope is set and current is true, search will return a single consent event (if it exists). Note that the return value will be a JSON array and not a single object.

$ curl 'https://api.signatu.com/consent/v0/consents/search?issuer=foo.com&target=https%3A%2F%2Ffoo.com%2Fpolicy&subject=torgeir%40signatu.com&current=true&scope=marketing'
[
{
"id": "2242374e1394b7862d030c117cbc57df024f948f2e8dc53a3a63ef327e628d79",
"scope": "marketing",
"subject": "foo@bar.com",
"issuer": "https://foo.com",
"target": "https://foo.com/policy/v12",
"source": "https://foo.com/login",
"action": false,
"token": "VR6BCF",
"createdAt": "2016-12-12T11:38:01.000Z"
}
]

The Consent Receipt is available from /consents/{id}/receipt and will contain a JWT token.

$ curl 'https://api.signatu.com/consent/v0/consents/2242374e1394b7862d030c117cbc57df024f948f2e8dc53a3a63ef327e628d79/receipt' -H 'Authorization: Bearer qtWPEIYKjbKIlxzU4eIYPwvIUKY1xBhp'
{
"receipt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0b3JnZWlyQHNpZ25hdHUuY29tIiwicG9saWN5VXJsIjoiaHR0cHM6Ly9mb28uY29tL3BvbGljeSIsImlhdCI6MTQ4MTU0MjY4MSwicHVibGljS2V5IjoiaHR0cHM6Ly9zaWduYXR1LmNvbS9jb25zZW50L3NpZ25hdHUtand0LnB1YiIsImRhdGFDb250cm9sbGVyIjp7Im9yZyI6ImZvby5jb20ifSwiaXNzIjoiaHR0cHM6Ly9zaWduYXR1LmNvbS9jb25zZW50L2FwaS92MCIsImp0aSI6IlZSNkJDRiIsInNpZ25hdHUiOnsiY29uc2VudCI6eyJpZCI6IjIyNDIzNzRlMTM5NGI3ODYyZDAzMGMxMTdjYmM1N2RmMDI0Zjk0OGYyZThkYzUzYTNhNjNlZjMyN2U2MjhkNzkiLCJzdWJqZWN0IjoidG9yZ2VpckBzaWduYXR1LmNvbSIsImlzc3VlciI6ImZvby5jb20iLCJ0YXJnZXQiOiJodHRwczovL2Zvby5jb20vcG9saWN5Iiwic291cmNlIjoiaHR0cHM6Ly9mb28uY29tL2xvZ2luIiwic2NvcGUiOiJtYXJrZXRpbmciLCJhY3Rpb24iOmZhbHNlfX19.UxZZxSQebthRrQCJ9zt11dPX5Eo5nlZsPdcYiBZEfLDFCyV5kghsVyg__NLBE85LdcJ1kaIolZBvUcauJp70eogbgtyxgt_M_Pkw_cHIY_GCRBHDjMuDCVkhlYFR5g_mUDdMg0TRXvLIPxZXq-1JqYTgj3GmUZXeLqGQq9cU7c5-Wy_XZkNtb-GUihjBAvh8pkjT1RHd51KaMfJtRR1UpZkuh3c5EJ36yq5famOdTrQSUdNmAAb9n-3ep96jBcsXb9VOdhgl61vKdOLYZC1vxwfFZSAIOR3wNPIk0VkGf2212qyrL1r0l2Xsj-jdHx4E7jlhmNPLsMCkwsIydVY4nw"
}