uktrade / legal-basis-api

Legal Basis for Consent Service API Server

legal_basis_api

Allows DIT's services to set and retrieve marketing consent settings for their users.

Architecture

SVG | Visio

Documentation

Full documentation is available here: docs/, which includes a Postman collection.

Prerequisites

You will need:

• python3.10
• postgresql with version 12
• docker with version at least 18.02

Before starting the application, you will need to create a local .env file based on the sample provided:

cp config/sample.env config/.env

Additionally, you will then need to ask a team member for the sso credentials and update the AUTHBROKER_* values in the newly created.env file.

Development with Docker

To build and start the application with Docker simply run the following commands one after the other in your terminal:

docker-compose build
docker-compose run --rm web python manage.py migrate
docker-compose run --rm web python manage.py collectstatic
docker-compose up

Example code to register the granting or revoking of marketing consent

The API is Hawk-authenticated. From Python, the mohawk library can be used to sign requests:

import mohawk
import requests
import json

def hawk_request(method, url, data):
    header = mohawk.Sender({
        'id': 'REPLACE_ME',
        'key': 'REPLACE_ME',
        'algorithm': 'sha256'
    }, url, method, content_type='application/json', content=data).request_header

    requests.request(method, url, data=data, headers={
        'Authorization': header,
        'Content-Type': 'application/json',
    }).raise_for_status()

# To grant email marketing consent
hawk_request(
    method='POST',
    url="https://legal-basis-api.test/api/v1/person/",
    data=json.dumps({
        "consents": ["email_marketing"],
        "modified_at": "2021-08-27T16:37:32.229Z",
        "email": "[email protected]",
        "key_type": "email",
    }),
)

# To grant phone marketing consent
hawk_request(
    method='POST',
    url="https://legal-basis-api.test/api/v1/person/",
    data=json.dumps({
        "consents": ["phone_marketing"],
        "modified_at": "2021-08-27T16:37:32.229Z",
        "phone": "[phone]",  # In E.164 format
        "key_type": "phone",
    }),
)

# To revoke consent
# Note the modified_at is later than the modified_at of the corresponding grant.
# The legal-basis-api assumes the most recent according to this datetime is
# current, even if they arrived at the legal-basis-api out-of-order
hawk_request(
    method='POST',
    url="https://legal-basis-api.test/api/v1/person/",
    data=json.dumps({
        "consents": [],
        "modified_at": "2021-08-27T17:12:37.123Z",
        "phone": "[phone]",  # In E.164 format
        "key_type": "phone",
    }),
)