# Tokens

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 you to create consent tokens for your organization. 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 and the organization user ID.

{% hint style="info" %}
The token lifetime is set to `900` seconds (15 min) by default. Specify the `lifetime` property when sending the POST request to change it.
{% endhint %}

```javascript
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": 900, // Default lifetime 15 min (900)
    "metadata": {
        ...
    }
}
```

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

```javascript
{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 900,
    "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:

```javascript
{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 900,
    "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 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

```javascript
{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 900,
    "delegate": {
        "id": "<Internal ID to identify the delegate>",
        "name": "<Name of the delegate>",
        "metadata": {
            // Custom metadata of the delegate
            "department_id": "...",
            "country": "..."
        }
    }
}
```

## Approval workflows

By default, user choices in a Preferences Center are automatically stored and applied to the user consent status.

You can configure your organization to require users to be approved 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 `validations` field to indicate whether `email`, `signature`, or `file` validation should be applied when a user updates their preferences with a consent token:

```javascript
{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 900,
    "validations": {
        "email": {
            "enabled": true,
            "approval": true
        }
    }
}
```

## 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 consent token lifetime is 15 min. After fifteen minutes, 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.

{% hint style="warning" %}
Consent tokens are part of our premium plan. Please reach out to support to have your account enabled.
{% endhint %}

## Configure consent token name

By default, the query param name for the consent token is `token`. In certain use cases, it might be necessary to utilize a different consent token name (e.g. `token` is being used by one of your internal services or third-party vendors). In order to utilize a different name for the Didomi consent token, add `user.auth.tokenName` to your `window.didomiConfig` object.&#x20;

```javascript
<script type="text/javascript">
  window.didomiConfig = {
    user: {
      auth: {
        tokenName: didomiToken
      }
    }
  };
</script>
```

The query param name for the Didomi consent token will be configured for the supplied value in your `window.didomiConfig.user.auth.tokenName`.

For example: `https://mycompany.com?didomitoken=12345abcd`