Skip to main content

1.0 Introduction

This guide is for administrators of organisations configuring and using consent management. It provides instructions through a sandbox use case example, Unconditional Social Cash Transfer (USCT). The guide assumes that the consent Building Block (BB) is installed, and the admin user is configured in your environment or that you are consuming this service via

1.1 Sandbox use case example

The USCT is a governmental programme that helps families meet their essential well-being and safety needs and serves as their path to self-sufficiency. The net result of the cash payments is provided to financially disadvantaged or vulnerable people or households without requiring anything in return (i.e. without conditionality). Today, the GovStack sandbox USCT use case reflects only a fraction of Consent Management functionality, demonstrating how various civil servants operating on behalf of the government department or agency interact and affect the transfer of cash payments to beneficiaries.

In the current use case, a fictional enrolment officer receives user consent to use essential personal information from the Candidate database to enrol anyone on any available benefits package. As there is no direct role for the user, consent is given via an out-of-band process via the personal data dashboard. Additional BB components have been included for demonstration purposes:

Figure 1: USCT use case with Consent BB

Three actors in the Consent Management system have distinct roles, contributing to specific use cases that implement the desired functionality [1]. These actors, illustrated in Figure 02, form the fundamental dynamics of the ecosystem:

  1. An Administrator representing an organisation (data controller or PII controller) processing personal data relies on the Consent Management to facilitate compliance with consent-related regulations and ethical practices. They seek agreement (consent being one of the lawful bases) from individuals for processing their data, outlining the envisaged data processing activities. The Administrator also ensures that data usage aligns with the provisions stated in the granted consent and adjusts operations in response to any alterations in individual preferences.

Figure 02: Key actors and use cases

  1. Individuals (or data subject or PII principle) are the primary proprietors of their personal data and have the authority to grant or withhold consent for its use if the lawful basis of the process is of the type of consent, contract or legitimate interest1. Their engagement entails initiating and responding to consent requests, scrutinising data processing intentions and ultimately bestowing or retracting consent. Through this active involvement, individuals exercise control over their personal information and affirm their preferences.

When an organisation uses legitimate interest as lawful basis, it does not need to seek the individual’s consent for processing data, however the individual has the right to opt out.

  1. A data processing Auditor (or regulatory body) oversees and assures adherence to contracted and regulatory requisites within the system. By maintaining a vigilant stance, the Auditor upholds the integrity of the consent ecosystem, fostering trust between individuals and data processors.

These three actors collectively establish a harmonious and responsible consent system in which transparency, individual autonomy, and regulatory compliance converge to shape data processing parameters.

1.3 Consent workflow

The consent workflow, as per the specification of the input, takes a structured data agreement lifecycle comprising four phases [1]: 1) Definition, 2) Preparation, 3) Capture, and 4) Proof (also referred to as CRUD below), as illustrated below.

alt_text Figure 03: Consent or data agreement workflow

In the definition phase, the organisation (a data provider or data consumer) defines an agreement with a data policy that applies to the industry or sector-specific data usage as a template. While this phase is considered a “black box” to the Consent Management, it is an input leading to configuration and compatibility checks in all the following phases. This phase could follow a data protection impact assessment (DPIA) or similar based on applicable data regulations. In the preparation phase, the organisation that processes personal data (a data provider or a data consumer) configures the data agreement and relevant rules for its use. In the case of obtaining user consent, the lawful basis of processing is marked “Consent” or “Legitimate Interest”. For example, an organisation could also share personal data for third-party data. The preparation phase is carried out via the admin dashboard, described in section 2.1.

During the capture phase, an individual can review the data agreement, which, once agreed upon, is captured in a consent record by the organisation and stored for verification. This is described in section 2.2.

In the proof phase, the organisation (or an external auditor) can verify that it holds a valid record for performing data processing. This allows internal usage, and an auditor can verify and ensure that records are in place to process an individual's personal data. For example, in the USCT use case, the proof is used to check if the consent record exists, as described in section 2.3.

2.0 Consent Management user guide

2.1 Admin user

The organisation's admin user can orchestrate personal data processing via the admin dashboard. With the help of the dashboard, the admin user can perform all CRUD (create, read, update and delete) operations on Data agreements. The portal also audits user consent, revision handling, and compliance management.

You can try out using the demo environment. For login details, kindly contact us at Developer Support to obtain your login credentials.

2.1.1 Login to admin dashboard

The admin user can login and view the organisation's data agreements.

alt_text Figure 04: Login to Admin Dashboard Screen

2.1.2 Configure organisation

Here, the admin can provide details about the organisation, such as name, location, cover image, and logo.

alt_text Figure 05: Getting Started Screen

The admin user can configure the global data policy, which is visible when creating data agreements. The global data policy configuration is set up for an organisation.

Figure 06: Global Data Policy Configurations

2.1.3 Create data agreement

A data agreement is created based on an existing or new data policy template. Its status is Published or Saved. The consent agreement must be under version control to ensure an auditable trial.

Figure 07: Create Data Agreement

2.1.4 View data agreement

The admin user can view all DAs and their parameters, including the version number. Here, all previously published and newly created DAs are listed. The unpublished DAs are marked in red.

Figure 07: Read Data Agreement

2.1.5 Update data agreement

The DA is updated with the newly provided values. When using View DA, a new revision of the DA is created.

alt_text Figure 08: Update Data Agreement

2.1.6 Delete data agreement

This function allows the admin user to permanently delete a published or draft DA. A warning is provided before confirming a deletion.

Figure 09: Delete Data Agreement

2.2 Individuals

Individuals control the use of their personal data and have the authority to grant or revoke consent. This is exercised either actively in real time or via a privacy dashboard, which provides a transparent view of how their data is used and shared.

2.2.1 View data agreement

Here, the individual can view every data agreement signed with a specific organisation. Each processing purpose, e.g. marketing and campaign, corresponds with a data agreement.

Figure 10: View Data Agreements

2.2.2 Toggle consents

The View DA screen shown above can toggle ON and OFF for those DAs whose lawful basis of processing is legitimate interest and consent. In other words, this is where a user makes their preference for data sharing known.

alt_text Figure 10: Opt-in/out of data agreements

Here, the DAs' consent history can be seen. When an individual signs an agreement, this is automatically logged in the consent record.

alt_text Figure 11: View Consent History

2.3 Auditor

The Auditor oversees and assures adherence to legal and regulatory requirements within the system. The auditor can retrieve audit logs about a user's consent actions to check if specific actions have been performed. Each log includes the user’s identity, timestamp, consent and the operations performed.

When signed, consent records are tamper-proof and can be verified to check their integrity. By remaining vigilant, the Auditor preserves the integrity of the consent ecosystem, nurturing trust between individuals and data processors.

The following information can be viewed in the individual’s consent record (for lawful basis consent or legitimate interest): Record ID, timestamps and other operations such as lawful basis and usage purpose, etc. There is a filter option to fetch the records based on purpose or lawful basis. Each log record clearly shows where the individual has selected opt-in or opt-out for a corresponding data agreement.

alt_text Figure 12: View Consent Records

This API used to read consent records for an individual in the USCT scenario is:

Execute the API here

This has the following input:

dataAgreementIdThe data agreement ID (E.g. Process UCST payments)
X-ConsentBB-IndividualIdThe individual ID whose consent record is being fetched

Sample GET request:

curl -X GET "<dataAgreementID>" \
-H "accept: application/json"\
-H "authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ2dVl0YTZERy1nMHhRRXdiR1JKSHFWSThOWTh4a2RyQWhYR08yOHFRNlNJIn0.eyJleHAiOjE2OTg1OTg1NzYsImlhdCI6MTY5ODU5NjgzNiwianRpIjoiMzdhYzAwMDYtNjM0ZS00MWM0LWE1NTYtMjk5OWJmYWVjMWU3IiwiaXNzIjoiaHR0cHM6Ly9zdGFnaW5nLWNvbnNlbnQtYmItaWFtLmlncmFudC5pby9yZWFsbXMvQkItQ29uc2VudC1Vc2VycyIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiJkZmYxZjQwNC1jZWIyLTQzNTItYmY5Ny05MmY3NzA3MWM2YTgiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJpZ3JhbnQtaW9zLWFwcCIsInNlc3Npb25fc3RhdGUiOiI2MjRmNmVjNC02N2Q1LTRhM2YtOTU5MS02YmUzODQzMjI5MTYiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIi8qIl0sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJkZWZhdWx0LXJvbGVzLWJiLWNvbnNlbnQtdXNlcnMiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwic2lkIjoiNjI0ZjZlYzQtNjdkNS00YTNmLTk1OTEtNmJlMzg0MzIyOTE2IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhZG1pbkBsYWxzcmV0YWlsLmNvbSIsImdpdmVuX25hbWUiOiIiLCJmYW1pbHlfbmFtZSI6IiIsImVtYWlsIjoiYWRtaW5AbGFsc3JldGFpbC5jb20ifQ.1GdY16YnDoVW7ra7NYvMSIl_Em99Mg72upta9O03EtJ4QG-avf9WrP6j3zHt01PXWuMYPERaUoFDsBgJYbCdnVpc79SqLt0Zy9UMJJr3wSllbtdo1-hCXBHUlU410yAF_WunBrglgyjqX4_cq6dA9q6XwoqyAJwMbCWboBP497TURhCqZl4gCDXLZkp6BRAwfi5Re5ZqFlmOxD6MikYzpBEMxOmDn85lsVuc9mpNI-GlHdNVxBlMTjLKrdUMhPx5gR9iSnWtSnQQPJOme4Ekw9A2Pqs1HgRi4mA8OOIamXxgV35OYfhYiVc23PxddpdFj1Zo8X2jUdFACHkZBPOjOQ"\
-H "x-consentbb-individualid: <X-ConsentBB-IndividualId>"

The response received is as follows:

"consentRecord": {
"id": "string",
"dataAgreementId": "string",
"dataAgreementRevisionId": "string",
"dataAgreementRevisionHash": "string",
"individualId": "string",
"optIn": false,
"state": "unsigned",
"signatureId": "string"}

From the API schema description:


3.0 Conclusions

This user guide is provided for GovStack Sandbox users. The current Sandbox use case (USCT) only uses a small number of the functions of the Consent Management. Hence, we recommend viewing our full demonstration recorded for a Data4Diabetes application scenario [2]. Please note, however, that this was recorded earlier and may have used an earlier version of the Consent Management UI, interfaces, APIs, etc.


  1. Govstack Consent BB Software Design Specification

  2. Data4Diabetes Application demo using Consent BB, Available at: (Embedded below)

Demo video