Didomi - Developers documentation
  • Introduction
  • SDKs
    • Introduction
    • Web SDK
      • Getting started
      • Tags and vendors management
        • Tags management
          • Events & Variables
            • Deprecated
            • Custom events
          • Tag managers
            • Adobe Launch/DTM
            • Eulerian
            • Google Tag Manager
              • Configure the Didomi / GTM integration
              • Didomi's GTM template
            • Tealium
            • Other tag managers
        • Custom Didomi <script> tags
        • Third-party integrations
          • Google Ad Manager / AdSense
            • GDPR via Non-Personalized Ads
              • Share consent and load/refresh ads
              • Share consent without loading or refreshing ads
            • US states laws
          • Google Consent Mode V2
          • Kameleoon
          • Piano Analytics (AT Internet)
          • Prebid
            • GDPR via IAB TCF
            • US states laws
          • Salesforce DMP (Krux)
        • IAB frameworks
        • Programmatic API
      • Configuration
        • Bots (SEO & Performance tools)
        • Configuration by URL
        • Cookies and storage
        • Custom domains for events
        • Notice
          • Behavior
          • Interactions
          • Look and feel
        • Preferences
        • Theme
      • AB tests
      • Custom domain
        • Domain delegation
        • Reverse proxy
      • Share consents between domains
      • Share consents across devices
      • Pass user choices in query string
      • Serve Didomi assets from your domain
      • Reference
        • API
          • Deprecated
        • Events
      • Performance
      • Versions
    • Mobile and TV SDKs
      • Android and Android TV
        • Setup
        • Logging
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • iOS and tvOS
        • Setup
        • Logging
        • App Tracking Transparency (iOS 14.5+)
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • Unity
        • Setup
        • Reference
        • Versions
        • Troubleshooting
      • React Native
        • Setup
        • Reference
          • Deprecated
        • Versions
      • Flutter
        • Setup
        • Reference
        • Versions
      • Consent notice
        • Getting started
        • Customize the notice
        • Customize the preferences popup
        • Customize the theme & UI
        • Load notice by ID
      • Third-party SDKs
      • Share consents across devices
      • Share consent with WebViews
      • Google Consent Mode v2
      • FAQ
    • AMP SDK
      • Blocking Behaviors
        • Load immediately on page load
        • Load only after consent (positive or negative)
        • Load only after positive consent
      • Consent status for vendors
    • Help & Support
  • API
    • Introduction
      • Authentication
      • Errors
      • Pagination
      • Filters
      • Caching
      • Rate limiting
      • Quotas
      • Translations
    • Data Manager
      • Regulations
      • Configuration Tree
      • Purposes
        • Purposes & Vendors Numerical IDs
      • Preferences Library
      • User Rights
    • Widgets
      • Consent notices
        • Notices
        • Configurations
        • Multi-Regulation Configurations
          • Migration of Existing Notices and API Updates
        • Deployments
        • Tutorials
          • Create and publish a consent notice
          • Create and publish a multi-regulation consent notice
      • Privacy widgets
        • Create a widget
        • Retrieve widgets
        • Edit a widget
          • Content & Design
            • Themes & Shapes
            • Components
              • auth
              • dsar_form
              • footer
              • header
              • preference
              • preference_value
              • save
              • section
              • sections
            • Options
          • Purposes & preferences
          • Settings
        • Deploy a Widget
          • Use your own subdomain
          • Use your own domain
          • Implement an embeddable widget on your website
        • Authentication
          • Manage authentication providers
          • Authenticate your end-user
        • Archive a widget
        • Headless widgets
          • Public Methods
          • Custom elements
          • Custom events
          • Event listeners
        • Tutorial
          • Launch a Preference Center from a mobile app
    • Compliance Reports
      • Properties
      • Reports
      • CSV format reference
      • Websites
    • Consents and Preferences
      • Events
        • Generate IAB TCF consent string
      • Links
      • Proofs
      • Tokens
      • Secrets
      • Users
      • Tutorial
        • Collect and operate data
    • Privacy Requests
      • Requests
      • Notes
      • Links
      • Emails
  • Integrations
    • Introduction
      • Quotas
    • Generic integrations
      • Batch export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
        • Exported data
          • Notices consents
        • Logs
      • Webhooks
      • Batch import
      • Analytics export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
    • Third-party apps
      • CMP integrations
        • Didomi-mParticle integration for your CMP
        • Deploy Didomi’s SDK for your Adobe Commerce website
      • Preference Management Platform integrations
        • Actito
        • Adobe Campaign Classic
        • Adobe Experience Cloud
        • Adobe Marketo Engage
        • Adobe Source Connector
        • Braze
        • Dotdigital
        • Hubspot
        • Mailchimp
        • Microsoft Dynamics 365
        • Salesforce Marketing Cloud
        • Salesforce Sales & Service Cloud
        • Selligent
        • Brevo (ex Sendinblue)
    • Tutorials
      • Configure a HTTP webhook
      • Configure a batch export
      • Configure an analytics export
    • Emailing
      • Configurations
        • Actito Email
        • Actito SMS
        • Adobe Campaign Classic
        • Adobe Campaign Standard
      • Emails
        • Templates
        • Manage your templates
Powered by GitBook
On this page

Last updated 1 year ago

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 .

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.

💡 The token lifetime is set to 900 seconds (15 min) by default. Specify the property lifetime when sending the POST request to change it.

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

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:

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

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 user 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 validation field to indicate wether email, signature or file validation should be applied when a user updates their preferences with a consent token:

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:

Keep in mind that the default consent tokens 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.

Consent Tokens are part of our premium plan. Please reach out to support to get your account enabled

{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 900,
    "event": {
        "metadata": {
            // Event metadata
        },
        
        "user": {
            "metadata": {
                // User metadata
            }
        }
    }
}
{
    "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": "..."
        }
    }
}
{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 900,
    "validations": {
        "email": {
            "enabled": true,
            "approval": true
        }
    }
}
https://privacy.company.com/?token={id_token}
  1. API
  2. Consents and Preferences

Tokens

PreviousProofsNextSecrets
  • Create a token
  • Metadata
  • Access delegation
  • Approval workflows
  • Preferences Center
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 15min (900)
    "metadata": {
        ...
    }
}
{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 900,
    "metadata": {
        ...
    },
    "id_token": "SKJ2..."
}
https://api.didomi.io/docs/