UID2-6592: Document UID2 token validator in integration guides

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

@@ -192,6 +192,14 @@ If the input data doesn't have a valid email or phone number format, or if the p
 
 You can use this tool to verify that your internal processes are set up to correctly create normalized, hashed, and encoded values for UID2.
 
+## UID2 Token Validator
+
+:::note
+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).
+
 ## Troubleshooting
 
 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

@@ -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 that your token generation workflow is correct.
+hide_table_of_contents: false
+sidebar_position: 02
+displayed_sidebar: docs
+---
+
+import Link from '@docusaurus/Link';
+
+# 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 your token generation process is correct.
+
+## 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 <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.
+
+## Prerequisites
+
+To use the UID2 Token Validator, you need:
+
+- A **UID2 API Key** (Client Key)
+- A **UID2 Client Secret**
+
+If you do not have these, see [API Keys](../portal/api-keys.md) for instructions on creating them in the UID2 Portal.
+
+## Using the Token Validator
+
+Enter your **API Key** (Client Key) and **Client Secret** in the fields at the top of the Token Validation section.
+
+Select the **Operator** (environment) you want to validate against. For information about UID2 environments, see [Environments](../getting-started/gs-environments.md).
+
+### Validate a Single Token
+
+1. Under **Input Mode**, select **Single Validation**.
+2. In the **Identifier** field, enter the DII you used to generate the token. This can be:
+   - A raw email address
+   - A raw phone number
+   - A Base64-encoded email hash
+   - A Base64-encoded phone hash
+3. Select the **Identifier Type** that matches your input.
+4. In the **Token** field, paste the UID2 token you want to validate.
+5. Click **Validate Tokens**.
+
+### Validate Multiple Tokens (CSV)
+
+To validate a batch of token-identifier pairs:
+
+1. Under **Input Mode**, select **CSV**.
+2. Prepare a CSV file with the following columns: 
+   - `identifier`: The DII (raw email, raw phone, email hash, or phone hash)
+   - `identifier_type`: Either `email`, `phone`, `email_hash` or `phone_hash`
+   - `token`: The UID2 token to validate.
+3. Upload the CSV file.
+4. Click **Validate Tokens**.
+
+## Interpreting Validation Results
+
+After clicking **Validate Tokens**, the **Validation Results** table displays a row for each token-identifier pair:
+
+| Column | Description |
+|---|---|
+| Identifier | The DII you entered. |
+| Identifier Type | `email`, `phone`, `email_hash` or `phone_hash`. |
+| Normalized Hash | The Base64-encoded SHA-256 hash of the normalized DII. |
+| Token | The token you submitted. |
+| Validation | The result of the validation. For details, see the following table. |
+
+The **Validation** column reflects the response from the [POST&nbsp;/token/validate](../endpoints/post-token-validate.md) endpoint.
+
+| Validation Result | Meaning |
+|---|---|
+| `Token matches identifier` | The token matches the provided DII. This means that 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. |
+| `Failed: Invalid token` | The token is malformed and cannot be parsed. |
+| `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 produced 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).
+:::

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

@@ -2,4 +2,6 @@ import Link from '@docusaurus/Link';
 
 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).
 
-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).

sidebars.js

@@ -382,6 +382,7 @@ const fullSidebar = [
         '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',
         'getting-started/gs-opt-out',
         'ref-info/ref-operators-public-private',
         'ref-info/ref-integration-approaches',
@@ -501,8 +502,9 @@ const sidebars = {
     'guides/integration-databricks',
     'guides/integration-aws-entity-resolution',
     'guides/advertiser-dataprovider-endpoints',
-    'sharing/sharing-bid-stream'
-    ),
+    'sharing/sharing-bid-stream',
+    'ref-info/ref-token-validator'
+  ),
 
   sidebarDataProviders: removeItems(fullSidebar, 
     'overviews/overview-publishers',
@@ -541,8 +543,9 @@ const sidebars = {
     'endpoints/post-token-generate',
     'endpoints/post-token-validate',
     'endpoints/post-token-refresh',
-    'sharing/sharing-bid-stream'
+    'sharing/sharing-bid-stream',
+    'ref-info/ref-token-validator'
   ),
 
 };
-module.exports = sidebars;
+module.exports = sidebars;