Consent tokens are JSON Web Tokens that allow users to access their consent data and update it. Create consent tokens when you need users to be able to make HTTP requests to our consents API directly from their browsers. Consent tokens can also be provided to Preferences Centers to create pre-authenticated links to use on your website or mobile app, in emails, etc.

The /consents/tokens endpoint of the API allows creating consent tokens for your organizations. For a full reference of the endpoint and the resources that it returns, visit https://api.didomi.io/docs/.

Create a token

To create a consent token for a user, send a POST request to https://api.didomi.io/consents/tokens and specify the organization ID, the organization user ID and (optionally) the lifetime (in seconds) of the token.

POST https://api.didomi.io/consents/tokens?organization_id=<ID of your organization>
{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 3600,
    "metadata": {
        ...
    }
}

The API will respond with the created token in the id_token field:

{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 3600,
    "metadata": {
        ...
    },
    "id_token": "SKJ2..."
}

Metadata

When creating a consent token, you can specify metadata to apply to all events created by a user with the consent token. This allows you to identify the events and the user with custom properties to store additional information and links to your internal systems.

The format of the metadata object is a free-form object described for Events. You can include information linked to the event or to the user.

Example:

{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 3600,
    "metadata": {
        // Event metadata
        ...
        
        "user": {
            // User metadata
            ...
        }
    }
}

Access delegation

A common use case for metadata is tracking access delegation: allowing a user to manage preferences on behalf of another user and keeping track of that access. For instance, companies allow internal employees using their CRM or HelpDesk software to manage preferences for their customers. Adding custom metadata allows keeping track of what employee modified preferences for users.

Example - Tracking an internal employee ID and their department for every event they create with a consent token

{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 3600,
    "metadata": {
        "employee_id": "123456",
        "department_id": "sales"
    }
}

Validation

When a user makes choices in a Preferences Center, their choices can be validated in multiple ways: by sending confirmation emails, asking for a signature, etc. You can configure a default validation method for your Preferences Center (or no validation).

When creating a consent token, you can override the default validation method used to force a specific method when preferences are modified by a user with the consent token. Use the validation field to indicate what validation method should be applied when a user updates their preferences with a consent token:

{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 3600,
    "validation": "signature"
}

Preferences Center

If authentication is enabled for your preferences center, you can generate consent tokens to create pre-authenticated links.

Create a consent token and append it to your preferences center URL in a token query-string parameter. Example:

https://privacy.company.com/?token={id_token}

Keep in mind that the default lifetime of consent tokens is 1 hour. After one hour, the link will expire and users will need to authenticate again. If you use tokens for links that have a long lifetime (in emails, for instance), make sure to specify the lifetime when creating the token.