UID2-6592: Document UID2 token validator in integration guides by BehnamMozafari · Pull Request #1001 · IABTechLab/uid2docs

BehnamMozafari · 2026-03-06T03:35:04Z

Added new reference page "UID2 Token Validator" giving an overview and instructions
Linked to reference page in "Preparing DII for Processing" section of integration guides
Linked to tool reference page in "Normalization and Encoding"

…ink error

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

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

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

genwhittTTD

Looks good! Few small edits and I sent the proposed updates to the sidebars file via Slack.

Great work.

genwhittTTD · 2026-03-06T16:14:09Z

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

+## UID2 Token Validator
+
+:::note
+This section is for publishers only. Publishers are the only participants who should generate [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) using directly identifying information (DII).


Suggest remove "should" here. Publishers are the only participants who can and do, I think. "should" implies it's possible for other participants to do so, which is hopefully not true.

Suggested change

This section is for publishers only. Publishers are the only participants who should generate [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) using directly identifying information (DII).

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).

genwhittTTD · 2026-03-06T16:15:37Z

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

+This section is for publishers only. Publishers are the only participants who should generate [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) using directly identifying information (DII).
+:::
+
+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).


All good here except two small things:

end to end is not a modifier here, so use separate words, no hyphens:

"to validate ... end to end"

When used as a modifier it would be correct: for example, "end-to-end workflow"

serial comma after hashed -- normal in the US.

Suggested change

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).

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).

genwhittTTD · 2026-03-06T16:16:41Z

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

@@ -0,0 +1,81 @@
+---
+title: UID2 Token Validator
+description: How to use the UID2 Token Validator to validate UID2 tokens against source DII and confirm your token generation workflow is correct.


Suggest add "that":

"and confirm that your..."

Tiny bit clearer

genwhittTTD · 2026-03-06T16:20:11Z

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

+
+# UID2 Token Validator
+
+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 token generation is working correctly.


"to confirm that token generation is working correctly." sounds as though we're checking to make sure things are functioning correctly on our side. In fact, we're checking that they are doing their steps correctly (I think).

Suggest:

Suggested change

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 token generation is working correctly.

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.

(second person, "you", is good, as you've used later -- more direct.)

genwhittTTD · 2026-03-06T16:24:10Z

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

+
+## Overview
+
+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 token that is unique to the publisher and will not match tokens generated by other publishers, data providers, or advertisers' CRM uploads.


Technical question here. I thought that a publisher token IS unique to the publisher, and does not, must not, match tokens generated by other publishers. I believe it is. I could well be wrong. Would appreciate to check. I might be getting mixed up with Sharing functionality.

I think what we are trying to say is simply that if there is an error in the earlier steps, the result is not a valid UID2 token.

genwhittTTD · 2026-03-06T16:39:12Z

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

+| Validation Result | Meaning |
+|---|---|
+| `Token matches identifier` | The token matches the provided DII, the token was generated from the correct normalized hash |
+| `Failed: Token does not match identifier` | The token does not match the provided DII, the most likely cause is incorrect normalization or hashing |


Two sentences.

Suggested change

| `Failed: Token does not match identifier` | The token does not match the provided DII, the most likely cause is incorrect normalization or hashing |

| `Failed: Token does not match identifier` | The token does not match the provided DII. The most likely cause is incorrect normalization or hashing. |

genwhittTTD · 2026-03-06T16:40:20Z

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

+
+| Validation Result | Meaning |
+|---|---|
+| `Token matches identifier` | The token matches the provided DII, the token was generated from the correct normalized hash |


Two sentences, with periods.

Suggested change

| `Token matches identifier` | The token matches the provided DII, the token was generated from the correct normalized hash |

| `Token matches identifier` | The token matches the provided DII. This means that the token was generated from the correct normalized hash. |

genwhittTTD · 2026-03-06T16:41:06Z

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

+| `Failed: {"status":"unauthorized"}` | The API credentials provided are invalid or unauthorized |
+
+:::tip
+If the result is **Failed: Token does not match identifier**, compare the **Normalized Hash** shown in the results with what your own implementation produces for the same DII. If they differ, the issue is in your normalization or hashing steps. 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).


produces > produced

genwhittTTD · 2026-03-06T16:42:38Z

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

-For details, see [Preparing Emails and Phone Numbers for Processing](../ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md).
+For details, see [Preparing Emails and Phone Numbers for Processing](../ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md).
+
+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).


Two small things here. End-to-end shoudl not be hyphenated, and add a comma after hashed (American usually does use this comma):

Suggested change

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).

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).

genwhittTTD · 2026-03-06T16:50:39Z

sidebars.js

        'getting-started/gs-encryption-decryption',
        'getting-started/gs-normalization-encoding',
        'ref-info/ref-preparing-emails-and-phone-numbers-for-processing',
+        'ref-info/ref-token-validator',


We need additional entries in sidebars.js to exclude it from the sidebar for the other personas.
Sending proposed revised sidebar via Slack.

BehnamMozafari added 5 commits March 6, 2026 14:07

Add token validator reference page

608693b

Add reference page to integration guides

993d585

Added reference to token validator in Normalization and Encoding page

77911b2

Removed reference to token validator from liveramp guide

1a2d224

Copied over ref-token-validator.md to japanese folder to fix broken l…

874040d

…ink error

BehnamMozafari requested review from genwhittTTD, jon8787 and sunnywu March 6, 2026 03:35

BehnamMozafari self-assigned this Mar 6, 2026

sunnywu reviewed Mar 6, 2026

View reviewed changes

docs/getting-started/gs-normalization-encoding.md Outdated Show resolved Hide resolved

sunnywu reviewed Mar 6, 2026

View reviewed changes

docs/ref-info/ref-token-validator.md Outdated Show resolved Hide resolved

sunnywu reviewed Mar 6, 2026

View reviewed changes

i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-token-validator.md Outdated Show resolved Hide resolved

BehnamMozafari added 2 commits March 6, 2026 15:22

Address review comments

063d814

Address review comments

5d4c139

genwhittTTD requested changes Mar 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

UID2-6592: Document UID2 token validator in integration guides#1001

UID2-6592: Document UID2 token validator in integration guides#1001
BehnamMozafari wants to merge 7 commits intomainfrom
bmz-UID2-6592-token-validator

BehnamMozafari commented Mar 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

genwhittTTD left a comment

Uh oh!

genwhittTTD Mar 6, 2026

Uh oh!

genwhittTTD Mar 6, 2026

Uh oh!

genwhittTTD Mar 6, 2026

Uh oh!

genwhittTTD Mar 6, 2026

Uh oh!

genwhittTTD Mar 6, 2026

Uh oh!

genwhittTTD Mar 6, 2026

Uh oh!

genwhittTTD Mar 6, 2026

Uh oh!

genwhittTTD Mar 6, 2026

Uh oh!

genwhittTTD Mar 6, 2026

Uh oh!

genwhittTTD Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	This section is for publishers only. Publishers are the only participants who should generate [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) using directly identifying information (DII).
	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).

	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).
	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).


		# UID2 Token Validator

		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 token generation is working correctly.


		## Overview

		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 token that is unique to the publisher and will not match tokens generated by other publishers, data providers, or advertisers' CRM uploads.

	\| `Failed: Token does not match identifier` \| The token does not match the provided DII, the most likely cause is incorrect normalization or hashing \|
	\| `Failed: Token does not match identifier` \| The token does not match the provided DII. The most likely cause is incorrect normalization or hashing. \|

	\| `Token matches identifier` \| The token matches the provided DII, the token was generated from the correct normalized hash \|
	\| `Token matches identifier` \| The token matches the provided DII. This means that the token was generated from the correct normalized hash. \|

Conversation

BehnamMozafari commented Mar 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

genwhittTTD left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants