-
Notifications
You must be signed in to change notification settings - Fork 50
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #404 from IABTechLab/gwh-APIDOCS-1941-nbsp-in-endp…
…oints add nbsp in API endpoint refs
- Loading branch information
Showing
43 changed files
with
167 additions
and
174 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -40,7 +40,7 @@ Here's what you need to know about this endpoint requests: | |
|
||
### Request Examples | ||
|
||
>IMPORTANT: To ensure that the API key used to access the service remains secret, the `POST /token/generate` endpoint must be called from the server side, unlike the [POST /token/refresh](post-token-refresh.md), which does not require using an API key. | ||
>IMPORTANT: To ensure that the API key used to access the service remains secret, the `POST /token/generate` endpoint must be called from the server side, unlike the [POST /token/refresh](post-token-refresh.md), which does not require using an API key. | ||
The following are unencrypted JSON request body examples for each parameter, one of which you should include in your token generation requests: | ||
|
||
|
@@ -122,7 +122,7 @@ Here is an example response when the the user has opted out. | |
| `identity_expires` | double | The UNIX timestamp (in milliseconds) that indicates when the advertising token expires. | | ||
| `refresh_from` | double | The UNIX timestamp (in milliseconds) that indicates when the UID2 SDK for JavaScript (see [UID2 SDK for JavaScript Reference Guide](../sdks/client-side-identity.md)) will start refreshing the UID2 token.<br/>TIP: If you are not using the SDK, consider refreshing the UID2 token from this timestamp, too. | | ||
| `refresh_expires` | double | The UNIX timestamp (in milliseconds) that indicates when the refresh token expires. | | ||
| `refresh_response_key` | string | A key to be used in a [POST /token/refresh](post-token-refresh.md) request for response decryption. | | ||
| `refresh_response_key` | string | A key to be used in a [POST /token/refresh](post-token-refresh.md) request for response decryption. | | ||
|
||
### Response Status Codes | ||
|
||
|
@@ -141,9 +141,9 @@ If the `status` value is anything other than `success`, the `message` field prov | |
|
||
| Type | Identity | Purpose | Next Endpoint | | ||
|:------|:-----------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------| | ||
| Email | `[email protected]` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified email address. | [POST /token/validate](post-token-validate.md) | | ||
| Email | `[email protected]` | Using this email for the request always generates an `optout` response. | [POST /token/generate](post-token-generate.md) | | ||
| Email | `[email protected]` | Using this email for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) | | ||
| Phone | `+12345678901` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified phone number. | [POST /token/validate](post-token-validate.md) | | ||
| Phone | `+00000000002` | Using this phone number for the request always generates an `optout` response. | [POST /token/generate](post-token-generate.md) | | ||
| Phone | `+00000000000` | Using this phone number for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) | | ||
| Email | `[email protected]` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified email address. | [POST /token/validate](post-token-validate.md) | | ||
| Email | `[email protected]` | Using this email for the request always generates an `optout` response. | [POST /token/generate](post-token-generate.md) | | ||
| Email | `[email protected]` | Using this email for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) | | ||
| Phone | `+12345678901` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified phone number. | [POST /token/validate](post-token-validate.md) | | ||
| Phone | `+00000000002` | Using this phone number for the request always generates an `optout` response. | [POST /token/generate](post-token-generate.md) | | ||
| Phone | `+00000000000` | Using this phone number for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -6,7 +6,7 @@ sidebar_position: 04 | |
--- | ||
|
||
# POST /token/refresh | ||
Generate a new [UID2 token](../ref-info/glossary-uid.md#gl-uid2-token) by sending the corresponding unexpired refresh token, returned by the [POST /token/generate](post-token-generate.md) endpoint. | ||
Generate a new [UID2 token](../ref-info/glossary-uid.md#gl-uid2-token) by sending the corresponding unexpired refresh token, returned by the [POST /token/generate](post-token-generate.md) endpoint. | ||
|
||
Used by: This endpoint is used mainly by publishers. | ||
|
||
|
@@ -16,14 +16,14 @@ Used by: This endpoint is used mainly by publishers. | |
|
||
`POST '{environment}/v2/token/refresh'` | ||
|
||
Add the content of the `refresh_token` value, returned in the response from the previous [POST /token/generate](post-token-generate.md) or `POST /token/refresh` operation, as the POST body. | ||
Add the content of the `refresh_token` value, returned in the response from the previous [POST /token/generate](post-token-generate.md) or `POST /token/refresh` operation, as the POST body. | ||
|
||
Here's what you need to know about this endpoint: | ||
|
||
- No encryption is required for token refresh requests. | ||
- If the request is successful, with an HTTP status code of 200, a new UID2 token or opt-out information is returned. | ||
- Successful responses, whether the response includes a new token or opt-out information, are encrypted. Error responses are not encrypted. | ||
- To decrypt responses, use the most recent `refresh_response_key` value for this token. The `refresh_response_key` value is returned in the response to the [POST /token/generate](post-token-generate.md) and `POST /token/refresh` operations. Each time a token is refreshed, a new `refresh_response_key` is returned. Be sure to use the most recent one to decrypt the current response. | ||
- To decrypt responses, use the most recent `refresh_response_key` value for this token. The `refresh_response_key` value is returned in the response to the [POST /token/generate](post-token-generate.md) and `POST /token/refresh` operations. Each time a token is refreshed, a new `refresh_response_key` is returned. Be sure to use the most recent one to decrypt the current response. | ||
|
||
### Path Parameters | ||
|
||
|
@@ -33,7 +33,7 @@ Here's what you need to know about this endpoint: | |
|
||
#### Testing Notes | ||
|
||
Using either of the following parameters in a [POST /token/generate](post-token-generate.md) request always generates an identity response with a `refresh_token` that results in a logout response when used with the `POST /token/refresh` endpoint: | ||
Using either of the following parameters in a [POST /token/generate](post-token-generate.md) request always generates an identity response with a `refresh_token` that results in a logout response when used with the `POST /token/refresh` endpoint: | ||
|
||
- The `[email protected]` email address | ||
- The `+00000000002` phone number | ||
|
@@ -102,7 +102,7 @@ An error response might look like the following: | |
| `identity_expires` | double | The UNIX timestamp (in milliseconds) that indicates when the UID2 token expires. | | ||
| `refresh_from` | double | The UNIX timestamp (in milliseconds) that indicates when the UID2 SDK for JavaScript (see [UID2 SDK for JavaScript Reference Guide](../sdks/client-side-identity.md)) will start refreshing the UID2 token, if the SDK is in use.<br/>TIP: If you are not using the SDK, consider refreshing the UID2 token from this timestamp, too. | | ||
| `refresh_expires` | double | The UNIX timestamp (in milliseconds) that indicates when the refresh token expires. | | ||
| `refresh_response_key` | string | A key to be used in a new [POST /token/refresh](post-token-refresh.md) request for response decryption. | | ||
| `refresh_response_key` | string | A key to be used in a new [POST /token/refresh](post-token-refresh.md) request for response decryption. | | ||
|
||
### Response Status Codes | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -35,7 +35,7 @@ Used by: This endpoint is used mainly by publishers. | |
|
||
| Body Parameter | Data Type | Attribute | Description | | ||
| :--- | :--- | :--- | :--- | | ||
| `token` | string | Required | The advertising token returned by the [POST /token/generate](post-token-generate.md) response. | | ||
| `token` | string | Required | The advertising token returned by the [POST /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`. | | ||
|
@@ -113,9 +113,9 @@ If the `status` value is anything other than `success`, the `message` field prov | |
|
||
## Using POST /token/validate to Test | ||
|
||
You can use this endpoint to test whether the [DII](../ref-info/glossary-uid.md#gl-dii) you are sending through [POST /token/generate](../endpoints/post-token-generate.md) is valid. Follow these steps. | ||
You can use this endpoint to test whether the [DII](../ref-info/glossary-uid.md#gl-dii) you are sending through [POST /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 /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—`email`, `email_hash`, `phone`, or `phone_hash`—with the corresponding value as listed in the table. | ||
1. Depending on whether the DII is a hashed or unhashed email address or phone number, send a [POST /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—`email`, `email_hash`, `phone`, or `phone_hash`—with the corresponding value as listed in the table. | ||
|
||
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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -12,7 +12,7 @@ import TabItem from '@theme/TabItem'; | |
|
||
For almost all UID2 [endpoints](../endpoints/summary-endpoints.md), requests sent to the endpoint must be [encrypted](#encrypting-requests) and responses from the endpoint must be [decrypted](#decrypting-responses). | ||
|
||
The only exception is that requests to the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint do not need to be encrypted. | ||
The only exception is that requests to the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint do not need to be encrypted. | ||
|
||
Here's what you need to know about encrypting UID2 API requests and decrypting respective responses: | ||
|
||
|
@@ -96,7 +96,7 @@ The following table describes the field layout for response decryption code. | |
|
||
### Response Example | ||
|
||
For example, a decrypted response to the [POST /token/generate](../endpoints/post-token-generate.md) request for an email address in the [preceding example](#request-example), may look like this: | ||
For example, a decrypted response to the [POST /token/generate](../endpoints/post-token-generate.md) request for an email address in the [preceding example](#request-example), may look like this: | ||
|
||
```json | ||
{ | ||
|
@@ -117,7 +117,7 @@ For example, a decrypted response to the [POST /token/generate](../endpoints/pos | |
|
||
This section includes an encryption and decryption code example in different programming languages. | ||
|
||
For the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint, the code takes the values for `refresh_token` and `refresh_response_key` that were obtained from a prior call to [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md). | ||
For the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint, the code takes the values for `refresh_token` and `refresh_response_key` that were obtained from a prior call to [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md). | ||
|
||
:::note | ||
For Windows, if you're using Windows Command Prompt instead of PowerShell, you must also remove the single quotes surrounding the JSON. For example, use `echo {"email": "[email protected]"}`. | ||
|
Oops, something went wrong.