Consentric API

Using the Consentric API - Java Step By Step Example

Universal Consent & Preference Management... Made simple.

QuickStart Guides
Additional Resources
Developer Plans

Prerequisites

When you signed up to Consentric you will have had an application created for you with some basic configuration and a client will have been configured for you to access the API. In order to work through this guide you will need the following details:

  • Your API client ID

  • Your API client secret

  • Your Consentric application ID

  • In ID of a privacy policy configured within your Consentric application

  • An ID of an Option configured within your Consentric application

  • An ID of a Permission Statement configured within your Consentric application

You will also need the following software installed:

Obtaining Consentric Entity IDs

If you don’t know the prerequisite Consentric entity IDs, you can retrieve these from the Consentric admin UI.

When you log into the Consentric UI, assuming you have the correct privileges, in the top right there is a button that allows you to enter the admin UI:

Once logged into the admin UI you can obtain an ID for one of your configured options from within the ‘Configuration’ screen

Within the ‘Privacy Policies’ screen you can obtain the ID of the privacy policy you intend to use:

Within the ‘Permission Statements’ screen you can retrieve the ID of the permission statement you intend to use:

Building your Java client

1. Initialise a Gradle Project

Make a directory for your client and execute the following command line within it

gradle init

  • You will be asked for various settings, use the following:

    • Type of project – application

    • Language to use – Java

    • Build script DSL – Groovy

    • Test framework – JUnit 4

    • Other settings – use defaults

    This will build you a skeleton application that can be executed with the command

./gradlew run

2. Add Unirest Dependency

This example uses the Unirest library making HTTP requests.

In your project’s build.gradle file remove the guava dependency that Gradle has added (we do need this) and add an implementation dependency for com.konghq:unirest-java so that your dependencies will look like this:

dependencies {
    implementation 'com.konghq:unirest-java:3.7.02'

    // Use JUnit test framework
    testImplementation 'junit:junit:4.12'
}

3. Declare your input parameters

In the generated project you will find a class named App within the src/main/java/ folder.

Add the following constant declarations to the top of this class, substituting your own values for the client ID and secret

public class App {

    private static final String CLIENT_ID = "<YOUR CLIENT ID>";
    private static final String CLIENT_SECRET = "<YOUR CLIENT SECRET>";
    private static final String API_AUDIENCE = "https://api.consentric.io";

4. Retrieve a JWT

Set the imports at the top of the App class to be the following:

import kong.unirest.HttpResponse;
import kong.unirest.JsonNode;
import kong.unirest.Unirest;

Now replace your main method with the following code:

public static void main(String[] args) {
    HttpResponse<JsonNode> httpResponse = Unirest.post("https://consentric.eu.auth0.com/oauth/token")
            .header("content-type", "application/json")
            .body("{\"client_id\":\"" + CLIENT_ID + "\",\"client_secret\":\"" + CLIENT_SECRET + "\",\"audience\":\"" + API_AUDIENCE + "\",\"grant_type\":\"client_credentials\"}")
            .asJson();

    if (httpResponse.getStatus() != 200) {
        System.out.printf("Error obtaining JWT: %s\n", httpResponse.getBody());
        System.exit(1);
    }

    String access_token = (String) httpResponse.getBody().getObject().get("access_token");

    System.out.printf("Retrieved JWT\n");
}

If you execute ./gradlew run your application will now execute and confirm that it has obtained a JWT

5. Create a Citizen

Add the following declarations to the top of your App class, substituting your own IDs:

private static final String BASE_URL = "https://api.consentric.io";
private static final String APPLICATION_ID = "<YOUR APPLICATION ID>";
private static final String PRIVACY_POLICY_ID = "<YOUR PRIVACY POLICY ID>";
private static final String OPTION_ID = "<YOUR OPTION ID>";
private static final String PERMISSION_STATEMENT_ID = "<YOUR PERMISSION STATEMENT ID>";

Add the following code to the end of your main method:

String citizenReference = UUID.randomUUID().toString();  // Citizen references should be unique strings

String citizen = "{\n" +
        "  \"applicationId\": \"" + APPLICATION_ID + "\",\n" +
        "  \"externalRef\": \"" + citizenReference + "\",\n" +
        "  \"givenName\": \"Test\",\n" +
        "  \"familyName\": \"Citizen2\",\n" +
        "  \"address\": {\n" +
        "    \"streetAddress\": \"23 Acacia Avenue\",\n" +
        "    \"addressLocality\": \"Trust Town\",\n" +
        "    \"addressRegion\": \"Gloucestershire\",\n" +
        "    \"addressCountry\": \"UK\",\n" +
        "    \"postalCode\": \"TT1 1AS\"\n" +
        "  }\n" +
        "}";

HttpResponse<JsonNode> createCitizenResponse = Unirest.post(BASE_URL + "/v1/citizens")
        .header("content-type", "application/json")
        .header("Authorization", "Bearer " + access_token)
        .body(citizen)
        .asJson();

System.out.printf("Citizen created: %s\n\n", createCitizenResponse.getBody().toPrettyString());

Your application will now create a new citizen in Consentric on each execution.

6. Submit a Transaction for the Citizen

Citizen contents and permissions are updated in Consentric by submitting transactions.

Each transaction can contain multiple changes to be applied and each change should specify the specific ‘Option’ to be changed and the new values to be applied.

A transaction should also state the IDs of the Privacy Policy and Permission Statement that that applied at the time the Citizen’s consents were obtained.

Add the following code to the end of your main method:

String citizenTransactions = "{\n" +
        "  \"applicationId\": \"" + APPLICATION_ID + "\",\n" +
        "  \"externalRef\": \"" + citizenReference + "\",\n" +
        "  \"changes\": [\n" +
        "    {\n" +
        "      \"optionType\": \"option\",\n" +
        "      \"optionId\": \"" + OPTION_ID + "\",\n" +
        "      \"justification\": \"consent\",\n" +
        "      \"state\": \"GRANTED\"\n" +
        "    }\n" +
        "  ],\n" +
        "  \"privacyPolicyId\": \"" + PRIVACY_POLICY_ID + "\",\n" +
        "  \"permissionStatementId\": \"" + PERMISSION_STATEMENT_ID + "\"\n" +
        "}";


HttpResponse<JsonNode> transactionPostResponse = Unirest.post(BASE_URL + "/v1/permissions/transactions")
        .header("content-type", "application/json")
        .header("Authorization", "Bearer " + access_token)
        .body(citizenTransactions)
        .asJson();

if (transactionPostResponse.getStatus() != 200) {
    System.out.printf("Error creating transaction: %s\n", transactionPostResponse.getBody());
    System.exit(1);
}

System.out.printf("transaction POST response: %s\n\n", transactionPostResponse.getBody().toPrettyString());

try {
    Thread.sleep(1000); // Allow consentric to process the transaction
} catch (InterruptedException e) {
    e.printStackTrace();
}

7. Retrieve a citizen's permissions

In this final step we add code to retrieve the created citizens permissions.

Add the following code to the end of your main method:

HttpResponse<JsonNode> permissionsResponse = Unirest.get(BASE_URL + "/v1/permissions")
        .header("content-type", "application/json")
        .header("Authorization", "Bearer " + access_token)
        .queryString("applicationId", APPLICATION_ID)
        .queryString("externalRef", citizenReference)
        .asJson();

if (permissionsResponse.getStatus() != 200) {
    System.out.printf("Error getting citizen permissions: %s\n", permissionsResponse.getBody());
    System.exit(1);
}

System.out.printf("Retrieved permissions: %s\n\n", permissionsResponse.getBody().toPrettyString());

On execution, your application will now create a citizen, updated their recorded permissions, and retrieve them again.

Summary

If you have followed the steps in this guide correctly you will have a basic Java client for the Consentric API

A completed example is available to be viewed and downloaded from GitHub

This is by no means a fully fledged production grade client, but should give any developer a good starting point for developing their own Consentric clients.