Skip to content

Commit 26b83c0

Browse files
BehnamMozafariBehnamMozafari
authored
Merge pull request #1001 from IABTechLab/bmz-UID2-6592-token-validator
UID2-6592: Document UID2 token validator in integration guides
2 parents d51f324 + 1525271 commit 26b83c0

File tree

5 files changed

+180
-5
lines changed

5 files changed

+180
-5
lines changed

‎docs/getting-started/gs-normalization-encoding.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,14 @@ If the input data doesn't have a valid email or phone number format, or if the p
192192

193193
You can use this tool to verify that your internal processes are set up to correctly create normalized, hashed, and encoded values for UID2.
194194

195+
## UID2 Token Validator
196+
197+
:::note
198+
This section is for publishers only. Publishers are the only participants who generate [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) using directly identifying information (DII).
199+
:::
200+
201+
To validate the full token generation pipeline end to end, confirming that <Link href="../ref-info/glossary-uid#gl-uid2-token">UID2 tokens</Link> generated from your normalized, hashed, and encoded values are correct, use the [UID2 Token Validator](../ref-info/ref-token-validator.md).
202+
195203
## Troubleshooting
196204

197205
In all scenarios, follow the steps on your side to prepare your DII for processing, and then check your resulting values by using the [UID2 hashing tool](https://hashing-tool.samples.uidapi.com/). If the results don't match, check each step to find the error.

‎docs/ref-info/ref-token-validator.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: UID2 Token Validator
3+
description: How to use the UID2 Token Validator to validate UID2 tokens against source DII and confirm that your token generation workflow is correct.
4+
hide_table_of_contents: false
5+
sidebar_position: 02
6+
displayed_sidebar: docs
7+
---
8+
9+
import Link from '@docusaurus/Link';
10+
11+
# UID2 Token Validator
12+
13+
The [UID2 Token Validator](https://token-validator.uidapi.com/) is a web-based tool that validates <Link href="../ref-info/glossary-uid#gl-uid2-token">UID2 tokens</Link> against their source <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> to confirm that your token generation process is correct.
14+
15+
## Overview
16+
17+
Publishers who generate UID2 tokens by providing DII sometimes receive tokens that appear valid but are unusable in the UID2 ecosystem. This happens when the normalization or hashing steps are not performed correctly. Because UID2 uses the normalized and hashed form of DII to derive the token, an error in either step produces a <Link href="../ref-info/glossary-uid#gl-raw-uid2">raw UID2</Link> that is unique to that publisher. This mismatched raw UID2 will not correspond to the one used by other participants for the same DII, meaning the publisher's tokens will not match up with those from other publishers, data providers, or advertisers' CRM uploads.
18+
19+
## Prerequisites
20+
21+
To use the UID2 Token Validator, you need:
22+
23+
- A **UID2 API Key** (Client Key)
24+
- A **UID2 Client Secret**
25+
26+
If you do not have these, see [API Keys](../portal/api-keys.md) for instructions on creating them in the UID2 Portal.
27+
28+
## Using the Token Validator
29+
30+
Enter your **API Key** (Client Key) and **Client Secret** in the fields at the top of the Token Validation section.
31+
32+
Select the **Operator** (environment) you want to validate against. For information about UID2 environments, see [Environments](../getting-started/gs-environments.md).
33+
34+
### Validate a Single Token
35+
36+
1. Under **Input Mode**, select **Single Validation**.
37+
2. In the **Identifier** field, enter the DII you used to generate the token. This can be:
38+
- A raw email address
39+
- A raw phone number
40+
- A Base64-encoded email hash
41+
- A Base64-encoded phone hash
42+
3. Select the identifier type that matches your input.
43+
4. In the **Token** field, paste the UID2 token you want to validate.
44+
5. Click **Validate Tokens**.
45+
46+
### Validate Multiple Tokens (CSV)
47+
48+
To validate a batch of token-identifier pairs:
49+
50+
1. Under **Input Mode**, select **CSV**.
51+
2. Prepare a CSV file with the following columns:
52+
- `identifier`: The DII (raw email, raw phone, email hash, or phone hash).
53+
- `identifier_type`: Either `email`, `phone`, `email_hash` or `phone_hash`.
54+
- `token`: The UID2 token to validate.
55+
3. Upload the CSV file.
56+
4. Click **Validate Tokens**.
57+
58+
## Interpret Validation Results
59+
60+
When you click **Validate Tokens**, the **Validation Results** table displays a row for each token-identifier pair, in the format shown in the following table.
61+
62+
| Column | Description |
63+
|---|---|
64+
| Identifier | The DII you entered. |
65+
| Identifier Type | `email`, `phone`, `email_hash` or `phone_hash`. |
66+
| Normalized Hash | The Base64-encoded SHA-256 hash of the normalized DII. |
67+
| Token | The token you submitted. |
68+
| Validation | The result of the validation. For details, see the following table. |
69+
70+
The **Validation** column reflects the response from the [POST&nbsp;/token/validate](../endpoints/post-token-validate.md) endpoint.
71+
72+
| Validation Result | Meaning |
73+
|---|---|
74+
| `Token matches identifier` | The token matches the provided DII. This means that the token was generated from the correct normalized hash. |
75+
| `Failed: Token does not match identifier` | The token does not match the provided DII. The most likely cause is incorrect normalization or hashing. |
76+
| `Failed: Invalid token` | The token is malformed and cannot be parsed. |
77+
| `Failed: {"status":"unauthorized"}` | The API credentials provided are invalid or unauthorized. |
78+
79+
:::tip
80+
If the result is **Failed: Token does not match identifier**, compare the **Normalized Hash** shown in the results with the value your own implementation produced for the same DII. If they differ, the issue is in your normalization or hashing steps. For details, see [Normalization and Encoding](../getting-started/gs-normalization-encoding.md) and [Preparing Emails and Phone Numbers for Processing](ref-preparing-emails-and-phone-numbers-for-processing.md).
81+
:::

‎docs/snippets/_snpt-preparing-emails-and-phone-numbers.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,6 @@ import Link from '@docusaurus/Link';
22

33
It's critical that the input data, which you are converting to UID2, is in an acceptable format. If it isn't, you won't get the expected results. For example, you must normalize phone numbers to include the country code, as explained in [Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization).
44

5-
For details, see [Preparing Emails and Phone Numbers for Processing](../ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md).
5+
For details, see [Preparing Emails and Phone Numbers for Processing](../ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md).
6+
7+
To validate the full token generation pipeline end to end, confirming that tokens generated from your normalized, hashed, and encoded values are correct, use the [UID2 Token Validator](../ref-info/ref-token-validator.md).

‎i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-token-validator.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: UID2 Token Validator
3+
description: How to use the UID2 Token Validator to validate UID2 tokens against source DII and confirm that your token generation workflow is correct.
4+
hide_table_of_contents: false
5+
sidebar_position: 02
6+
displayed_sidebar: docs
7+
---
8+
9+
import Link from '@docusaurus/Link';
10+
11+
# UID2 Token Validator
12+
13+
The [UID2 Token Validator](https://token-validator.uidapi.com/) is a web-based tool that validates <Link href="../ref-info/glossary-uid#gl-uid2-token">UID2 tokens</Link> against their source <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> to confirm that your token generation process is correct.
14+
15+
## Overview
16+
17+
Publishers who generate UID2 tokens by providing DII sometimes receive tokens that appear valid but are unusable in the UID2 ecosystem. This happens when the normalization or hashing steps are not performed correctly. Because UID2 uses the normalized and hashed form of DII to derive the token, an error in either step produces a <Link href="../ref-info/glossary-uid#gl-raw-uid2">raw UID2</Link> that is unique to that publisher. This mismatched raw UID2 will not correspond to the one used by other participants for the same DII, meaning the publisher's tokens will not match up with those from other publishers, data providers, or advertisers' CRM uploads.
18+
19+
## Prerequisites
20+
21+
To use the UID2 Token Validator, you need:
22+
23+
- A **UID2 API Key** (Client Key)
24+
- A **UID2 Client Secret**
25+
26+
If you do not have these, see [API Keys](../portal/api-keys.md) for instructions on creating them in the UID2 Portal.
27+
28+
## Using the Token Validator
29+
30+
Enter your **API Key** (Client Key) and **Client Secret** in the fields at the top of the Token Validation section.
31+
32+
Select the **Operator** (environment) you want to validate against. For information about UID2 environments, see [Environments](../getting-started/gs-environments.md).
33+
34+
### Validate a Single Token
35+
36+
1. Under **Input Mode**, select **Single Validation**.
37+
2. In the **Identifier** field, enter the DII you used to generate the token. This can be:
38+
- A raw email address
39+
- A raw phone number
40+
- A Base64-encoded email hash
41+
- A Base64-encoded phone hash
42+
3. Select the identifier type that matches your input.
43+
4. In the **Token** field, paste the UID2 token you want to validate.
44+
5. Click **Validate Tokens**.
45+
46+
### Validate Multiple Tokens (CSV)
47+
48+
To validate a batch of token-identifier pairs:
49+
50+
1. Under **Input Mode**, select **CSV**.
51+
2. Prepare a CSV file with the following columns:
52+
- `identifier`: The DII (raw email, raw phone, email hash, or phone hash).
53+
- `identifier_type`: Either `email`, `phone`, `email_hash` or `phone_hash`.
54+
- `token`: The UID2 token to validate.
55+
3. Upload the CSV file.
56+
4. Click **Validate Tokens**.
57+
58+
## Interpret Validation Results
59+
60+
When you click **Validate Tokens**, the **Validation Results** table displays a row for each token-identifier pair, in the format shown in the following table.
61+
62+
| Column | Description |
63+
|---|---|
64+
| Identifier | The DII you entered. |
65+
| Identifier Type | `email`, `phone`, `email_hash` or `phone_hash`. |
66+
| Normalized Hash | The Base64-encoded SHA-256 hash of the normalized DII. |
67+
| Token | The token you submitted. |
68+
| Validation | The result of the validation. For details, see the following table. |
69+
70+
The **Validation** column reflects the response from the [POST&nbsp;/token/validate](../endpoints/post-token-validate.md) endpoint.
71+
72+
| Validation Result | Meaning |
73+
|---|---|
74+
| `Token matches identifier` | The token matches the provided DII. This means that the token was generated from the correct normalized hash. |
75+
| `Failed: Token does not match identifier` | The token does not match the provided DII. The most likely cause is incorrect normalization or hashing. |
76+
| `Failed: Invalid token` | The token is malformed and cannot be parsed. |
77+
| `Failed: {"status":"unauthorized"}` | The API credentials provided are invalid or unauthorized. |
78+
79+
:::tip
80+
If the result is **Failed: Token does not match identifier**, compare the **Normalized Hash** shown in the results with the value your own implementation produced for the same DII. If they differ, the issue is in your normalization or hashing steps. For details, see [Normalization and Encoding](../getting-started/gs-normalization-encoding.md) and [Preparing Emails and Phone Numbers for Processing](ref-preparing-emails-and-phone-numbers-for-processing.md).
81+
:::

‎sidebars.js‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -382,6 +382,7 @@ const fullSidebar = [
382382
'getting-started/gs-encryption-decryption',
383383
'getting-started/gs-normalization-encoding',
384384
'ref-info/ref-preparing-emails-and-phone-numbers-for-processing',
385+
'ref-info/ref-token-validator',
385386
'getting-started/gs-opt-out',
386387
'ref-info/ref-operators-public-private',
387388
'ref-info/ref-integration-approaches',
@@ -501,8 +502,9 @@ const sidebars = {
501502
'guides/integration-databricks',
502503
'guides/integration-aws-entity-resolution',
503504
'guides/advertiser-dataprovider-endpoints',
504-
'sharing/sharing-bid-stream'
505-
),
505+
'sharing/sharing-bid-stream',
506+
'ref-info/ref-token-validator'
507+
),
506508

507509
sidebarDataProviders: removeItems(fullSidebar,
508510
'overviews/overview-publishers',
@@ -541,8 +543,9 @@ const sidebars = {
541543
'endpoints/post-token-generate',
542544
'endpoints/post-token-validate',
543545
'endpoints/post-token-refresh',
544-
'sharing/sharing-bid-stream'
546+
'sharing/sharing-bid-stream',
547+
'ref-info/ref-token-validator'
545548
),
546549

547550
};
548-
module.exports = sidebars;
551+
module.exports = sidebars;

0 commit comments

Comments
 (0)