Skip to content

Update /token/validate docs #959

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vishalegbert-ttd merged 4 commits into from
Dec 7, 2025
Merged

Update /token/validate docs #959

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c3d75cb
Update /token/validate docs
vishalegbert-ttd Dec 4, 2025
9c55516
Address feedback
vishalegbert-ttd Dec 5, 2025
e91dbd1
minor updates
genwhittTTD Dec 5, 2025
0d1150e
minor updates
genwhittTTD Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions docs/endpoints/post-token-validate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,11 @@ The integration environment and the production environment require different <Li

| Body Parameter | Data Type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `token` | string | Required | The advertising token returned by the [POST&nbsp;/token/generate](post-token-generate.md) response. |
| `email` | string | Conditionally Required | The email address for token validation.<br/>The only valid value is: `[email protected]`. |
| `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of the [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address for token validation (`[email protected]`).<br/>The only valid value is: `ntI244ZRTXwAwpki6/M5cyBYW7h/Wq576lnN3l9+W/c=`. |
| `phone` | string | Conditionally Required | The [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number for which to generate tokens.<br/>The only valid value is: `+12345678901`. |
| `phone_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hash of a [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number.<br/>The only valid value is: `EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=`. |
| `token` | string | Required | The advertising token returned by the [POST&nbsp;/token/generate](post-token-generate.md) response.<br/><br/>You may only validate advertising tokens that have been generated with your own credentials. |
| `email` | string | Conditionally Required | The email address for token validation. |
Copy link
Collaborator

@genwhittTTD genwhittTTD Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it's not true that the only valid value is [email protected], we now have to tell them what the email address is... where can they get this value? Or can it be anything? We should say -- particularly since this is a change.

Also: was it true for earlier versions but not true in a new version? If so... not sure how we address that but if we update the copy to say something like they can use any value, and it isn't true if the person is on an earlier version, that's not good.

Copy link
Contributor Author

@vishalegbert-ttd vishalegbert-ttd Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, any DII can be used now

The update was made to the existing version of the endpoint, so clients using the existing endpoint can now validate any DII. I haven't made it clear that any DII can be used as I'm not entirely sure how to word it, but happy for you to take a stab at this

Copy link
Collaborator

@genwhittTTD genwhittTTD Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vishalegbert-ttd thx. Checking in suggested wording on this one. If you don't like it no worries, change it.

| `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of the [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address for token validation. |
| `phone` | string | Conditionally Required | The [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number for which to generate tokens. |
| `phone_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hash of a [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number. |

### Request Examples

Expand Down Expand Up @@ -111,7 +111,7 @@ A successful decrypted response returns a boolean value that indicates the valid

| Property | Data Type | Description |
| :--- | :--- | :--- |
| `body` | boolean | A value of `true` indicates that the email address, phone number, or the respective hash specified in the request is the same as the one used to generate the advertising token.<br/>A value of `false` indicates any of the following:<br/>- The request included an invalid advertising token.<br/>- The email address, phone number, or the respective hash specified in the request is not one of the four valid values specified in the [Unencrypted JSON Body Parameters](#unencrypted-json-body-parameters) table. |
| `body` | boolean | A value of `true` indicates that the email address, phone number, or the respective hash specified in the request is the same as the one used to generate the advertising token.<br/><br/>A value of `false` indicates that the email address, phone number, or the respective hash specified in the request is not the same as the oned used to generated the advertising token. |

### Response Status Codes

Expand All @@ -120,7 +120,7 @@ The following table lists the `status` property values and their HTTP status cod
| Status | HTTP Status Code | Description |
| :--- | :--- | :--- |
| `success` | 200 | The request was successful. The response will be encrypted. |
| `client_error` | 400 | The request had missing or invalid parameters.|
| `client_error` | 400 | The request had missing or invalid parameters. |
| `unauthorized` | 401 | The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested operation. |

If the `status` value is anything other than `success`, the `message` field provides additional information about the issue.
Expand All @@ -129,8 +129,7 @@ If the `status` value is anything other than `success`, the `message` field prov

You can use this endpoint to test whether the <Link href="../ref-info/glossary-uid#gl-dii">DII</Link> that you are sending through [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) is valid. Follow these steps.

1. Depending on whether the DII is a hashed or unhashed email address or phone number, send a [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) request using one of the four valid options listed in the [Unencrypted JSON Body Parameters](#unencrypted-json-body-parameters) table&#8212;`email`, `email_hash`, `phone`, or `phone_hash`&#8212;with the corresponding value as listed in the table.

1. Send a [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) request using an `email`, `email_hash`, `phone` or `phone_hash` to generate an advertising token to validate.
2. Store the returned `advertising_token` value for use in the next step.
3. Send a `POST /token/validate` request using the `email`, `email_hash`, `phone`, or `phone_hash` value that you sent in Step 1, with the `advertising_token` that you saved in Step 2 as the `token` property value.
4. Check the response to the `POST /token/validate` request. The results indicate the success of your process, as follows:
Expand Down
Loading