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 when using 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.

Specify the event object to include metadata linked to the event or to the user:

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

Access delegation

Access delegation happens when a consent token is created to allow a third-party to modify the consents for an end user. The third-party is a "delegate" of the end user in that case and access delegation allows keeping track of events created by the delegate. For instance, companies allow internal employees using their CRM or HelpDesk software to manage preferences for their customers.

Provide the delegate property when creating a consent token to indicate access delegation. You can specify the ID and name of the delegate, and a use a generic metadata field to keep track of extra information on the delegate.

The delegate property automatically gets added to all events created from the consent token.

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,
    "delegate": {
        "id": "<Internal ID to identify the delegate>",
        "name": "<Name of the delegate>",
        "metadata": {
            // Custom metadata of the delegate
            "department_id": "...",
            "country": "..."
        }
    }
}

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.