| title | Tokenized Sharing Overview |
|---|---|
| description | Learn about the options for tokenized sharing. |
| hide_table_of_contents | false |
| sidebar_position | 4 |
| displayed_sidebar | docs |
import Link from '@docusaurus/Link';
In UID2, tokenized sharing means encrypting DII or raw UID2s into UID2 tokens and sharing the tokens with recipients who are authorized sharing participants. Using UID2 tokens helps protect raw UID2s end-to-end between the sender and receiver of the data, including when the data passes through unauthorized parties. Tokenized sharing is required for sharing in the bidstream or via pixels, but you can use it in any sharing use case.
Tokens are generated in one of the following ways:
- By encrypting raw UID2s into UID2 tokens: see Tokenized Sharing: Starting with a Raw UID2.
- By generating UID2 tokens directly from DII: see Tokenized Sharing: Starting with DII.
In many scenarios, UID2 data is shared in the form of a UID2 token. Key use cases are shown in the following table.
| Scenario | Sender | Receiver | Sharing Approach |
|---|---|---|---|
| Sending a UID2 to the bidstream | Publisher | DSP | See Tokenized Sharing in the Bidstream |
| Sending a UID2 in a tracking pixel | Any sharing participant | Any sharing participant | See Tokenized Sharing in Pixels |
| Sending UID2 tokens to another sharing participant | Any sharing participant, if all security requirements listed in Security Requirements for UID2 Sharing cannot be followed, or for any other reason. | Any sharing participant | See Tokenized Sharing from Raw UID2s |
For additional examples, see Sharing UID2s: Use Cases.
Sharing UID2s with another sharing participant via UID2 tokens is an option in any sharing scenario, but is required within the bidstream or in pixels. The process is a little different depending on the starting point, as shown in the following table.
Choose the integration option that's right for your implementation, and then click through for details.
| Starting Point | Encryption Option/Scenario | Link to Details |
|---|---|---|
| DII | Sharing UID2 tokens from DII in the bidstream | Tokenized Sharing in the Bidstream |
| DII | Sharing UID2 tokens from DII in tracking pixels | Workflow: Tokenized Sharing in Tracking Pixels |
| Raw UID2 | Sharing UID2 tokens from raw UID2s in creative pixels | Workflow: Tokenized Sharing in Creative Pixels |
| Raw UID2 | Sharing UID2 tokens from raw UID2s using an SDK | Implementing Sharing Encryption/Decryption with an SDK |
| Raw UID2 | Sharing UID2 tokens from raw UID2s using Snowflake | Implementing Sharing Encryption/Decryption Using Snowflake |
The steps that the receiver takes are similar for all approved sharing scenarios. The receiver must decrypt the UID2 token to arrive at the raw UID2. To do this, the receiver must have a UID2 Portal account and the sender must create a sharing relationship with the receiver in the UID2 Portal, so that the receiver can access the sender's decryption keys.
:::tip We recommend decrypting the tokens as soon as possible after receiving them, to avoid token expiration. See Best Practices for Managing Raw UID2s and UID2 Tokens. :::
The following implementation options are available for decrypting UID2 tokens.
| Starting Point | Decryption Option/Scenario | Link to Details |
|---|---|---|
| Token | C# / .NET SDK | SDK for C# / .NET: Usage for UID2 Sharers |
| Token | C++ SDK | SDK for C++: Usage for UID2 Sharers |
| Token | Java SDK | SDK for Java: Usage for UID2 Sharers |
| Token | Python SDK | SDK for Python: Usage for UID2 Sharers |
| Token | Snowflake | Snowflake Integration Guide: Usage for UID2 Sharers |
| Token | Decryption of UID2 tokens sent in the bidstream (DSPs only) | DSP Integration Guide: Decrypt UID2 Tokens for RTB Use |
The steps for tokenized sharing depend on whether you're starting with DII or with a raw UID2. This section includes the following:
- Tokenized Sharing: Starting with DII
- Example: DII to UID2 Token
- Tokenized Sharing: Starting with a Raw UID2
- Example: Raw UID2 to UID2 Token
Starting with DII is most common for publishers sharing in the bidstream and for sharing in tracking pixels.
If you're starting with DII, generate the UID2 token by following either of these paths:
-
Option 1 (Recommended): Generate UID2 token from DII using one of the UID2 SDKs or the POST /token/generate endpoint.
-
Option 2: Convert to raw UID2 and then encrypt:
-
Convert the input email address or phone number to a raw UID2, which you can store securely.
-
Encrypt the raw UID2 to create a UID2 token that you can share with another trusted UID2 sharing participant. For an example, see Example: Raw UID2 to UID2 Token.
-
Then, share the resulting UID2 token with another trusted UID2 sharing participant.
The following example shows sample values when converting input DII directly to a UID2 token.
| Input Example | Process/User | Result |
|---|---|---|
| user@example.com | Convert email/phone number to UID2 token | KlKKKfE66A7xBnL/DsT1UV/Q+V/r3xwKL89Wp7hpNllxmNkPaF8vdzenDvfoatn6sSXbFf5DfW9wwbdDwMnnOVpPxojkb8KYSGUte/FLSHtg4CLKMX52UPRV7H9UbWYvXgXC4PaVrGp/Jl5zaxPIDbAW0chULHxS+3zQCiiwHbIHshM+oJ== |
Setting up tokenized sharing to encrypt raw UID2s requires some steps by each participant:
- The sender, who encrypts the raw UID2 to create UID2 tokens and sends the tokens to an authorized sharing participant.
- The receiver, an authorized sharing participant who receives the UID2 tokens and decrypts them.
Tokenized sharing starting with a raw UID2 is common for sharing in creative pixels. It can also be used in other scenarios. For details, see Tokenized Sharing from Raw UID2s.
If you're starting with a raw UID2, follow these steps:
-
Encrypt the raw UID2, using one of the UID2 server-side SDKs or the UID2 Snowflake integration, to create a UID2 token that you can share with another trusted UID2 sharing participant. For an example, see Example: Raw UID2 to UID2 Token.
-
Share the resulting UID2 token with another trusted UID2 sharing participant.
The following example shows sample values when converting input DII to a raw UID2 and then encrypting the raw UID2 to create a UID2 token.
| Step | Input Example | Process/User | Result |
|---|---|---|---|
| 1 | user@example.com | Convert email/phone number to raw UID2: POST /identity/map endpoint |
K2jlbu2ldlpKL1z6n5bET7L3 g0xfqmldZPDdPTktdRQ= |
| 2 | K2jlbu2ldlpKL1z6n5bET7L3 g0xfqmldZPDdPTktdRQ= |
Encrypt raw UID2 to create a UID2 token: `encrypt()` function in applicable SDK. For example, for Java, see Usage for UID2 Sharers step 3. |
KlKKKfE66A7xBnL/DsT1UV/Q+V/r3xwKL89Wp7hpNllxmNkPaF8vdzenDvfoatn6sSXbFf5DfW9wwbdDwMnnOVpPxojkb8KYSGUte/FLSHtg4CLKMX52UPRV7H9UbWYvXgXC4PaVrGp/Jl5zaxPIDbAW0chULHxS+3zQCiiwHbIHshM+oJ== |
The UID2 token is designed so that even if the underlying raw UID2 remains the same, each time a UID2 token is generated from it, the token value is different. This means that the UID2 token can be seen by all but can only be used by UID2 participants that have access to the decryption key.
For example, UID2 tokens are regularly passed through the bidstream from a publisher to a DSP. Although a UID2 token might go through several parties, such as an SSP, it can be decrypted only by an authorized UID2 participant. On its journey through the bidstream, the UID2 token can safely pass through one or more intermediaries.
The same is true in tokenized sharing scenarios between UID2 sharing participants. A UID2 token can be passed through non-UID2 participants.
:::caution Pass-through is only permissible in a tokenized sharing scenario. A raw UID2 must not be passed through non-participants. :::