ConsentGrid API Reference

ConsentGrid uses predictable REST APIs for all resource-related operations and several RPC-style APIs for more specialized tasks. These APIs use standard HTTP verbs and return standard HTTP response codes. All APIs use encrypted communication (HTTPS) with the clients.

Accounts

ConsentGrid™ organizes all data and configuration under accounts. When you log in to the ConsentGrid™ UI or invoke an API, you choose an account to work with. ConsentGrid™ will modify or return data from the chosen account. When you create an object such as a consent form, or a data subject in an account, that object is accessible only when you're working in that account.

Account access is controlled by administrators. When you create an account, you become the administrator for it. An account administrator can add other users to the account, and manage their access rights within the account.

An account can be a test account or a live account. A test account has usage and storage limits. It is intended for development, test or evaluation work only.

Authentication

ConsentGrid works with two types of users:

User
A user is associated to an individual or an organization that can log in to the administrative UI. A user can obtain an access token that has a limited life span to invoke ConsentGrid™ APIs. Use the login menu "Access Token" option to generate your tokens.
API User
An API user represents a client application that can call ConsentGrid™ APIs only. An API user cannot log in to the administrative interface, or cannot call administrative APIs. The access keys for API accounts do not expire, and they must be kept a secret. If you think an access key is compromised, you can delete it and create a new key using the administration interface. Manage your access keys from the "Account Users" option in the login menu.

The access keys and tokens can be used in several ways:

Using HTTP basic authentication:
Authorization: Basic base64("apikey":token)
User name: the string apikey, without the quotes
Password: The api token
Bearer token:
Authorization: Bearer token
Some ConsentGrid™ APIs can be used from web applications (such as the Submit Consent Form API). Do not include access keys to invoke such APIs, refer to the specific documentation to see how these APIs are used.
Cookie Auth

You can call data subject session APIs to create a session for the data subject and obtain a cookie for your front-end to call some of the ConsentGrid™ APIs directly without authentication. The flow is as follows:

  • Call the createSubjectSession API from your backend with the data subject information, your API key, and a redirect URL targeting the next page in your application. This API will return a URL for your to redirect your users.
  • Once the user is redirected to the URL returned by createSubjectSession API, a session cookie is set, and the user is redirected back you the URL you gave.
  • You can now call some of the ConsentGrid™ APIs without API keys, using the cookie. To pass cookie information in AJAX calls, do not forget to add withCredentials: true:
        $.ajax({url:"https://aws.consentgrid.io/....",
            xhrFields: {
              withCredentials: true
            }
        )
        

JSON data

ConsentGrid recognizes the RFC3339 standard for dates:

{
  "dateTime": "2006-01-02T15:04:05Z07:00",
  "date": "2006-01-02",
  "time": "15:04:05Z07:00"
  }

Streaming

ConsentGrid uses concatenated or newline-delimited JSON streams.

{"id": "abc",...}{"id": "6526",...}{"id": "efa52",...}...
{"id": "abc",...}
{"id": "6526",...}
{"id": "efa52",...}
 ...

Errors

ConsentGrid uses the following standard HTTP status codes.

200 OK
Operation completed successfully. The response body contains an entity describing the result of the operation.
204 No Content
Operation completed successfully. There is no response body.
400 Bad Request
Malformed request, or unacceptable input value. Depending on the location of the error, the body may contain a JSON document describing the exact error.
401 Unauthorized
Required access key or domain information is missing.
403 Forbidden
The access key used in the call does not have sufficient privileges.
404 Not Found
The resource needed to complete the operation was not found. The body may contain a JSON document describing the exact error.
413 Payload too large
The request is too large for processing.
415 Unsupported media type
The request body contains content that is not recognized by the API.
500 Internal server error
A generic error message not described by any of the above. Depending on the error, the body may contain a JSON document describing the exact error.

Diagnostics

When possible, ConsentGrid APIs will return error diagnostic information in the following format:

{
  "operation": "checkConsent",
  "success": false,    
  "statusCode": 404,
  "type": "notfound",
  "severity": "fatal",
  "message":  "Subject not found"
}

Versioning

Data subjects and consent records are versioned objects. The first time a versioned object is created it is assigned version number 1. Subsequent modifications to a versioned object are written with increasing version numbers. For example, when a data subject is first created, it becomes v1 of that subject. If later the data subject is modified, the new version becomes v2, and the older v1 version is still kept. The v1 version can be accessed by the additional query parameter version=1 to the get subject API.