Skip to content

Commit

Permalink
Merge pull request #404 from IABTechLab/gwh-APIDOCS-1941-nbsp-in-endp…
Browse files Browse the repository at this point in the history
…oints

add nbsp in API endpoint refs
  • Loading branch information
genwhittTTD authored Jan 3, 2024
2 parents e8d4e63 + 6ffa633 commit bdadbae
Show file tree
Hide file tree
Showing 43 changed files with 167 additions and 174 deletions.
16 changes: 8 additions & 8 deletions docs/endpoints/post-token-generate.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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&nbsp;/token/refresh](post-token-refresh.md) request for response decryption. |

### Response Status Codes

Expand All @@ -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&nbsp;/token/validate](post-token-validate.md) |
| Email | `[email protected]` | Using this email for the request always generates an `optout` response. | [POST&nbsp;/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&nbsp;/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&nbsp;/token/validate](post-token-validate.md) |
| Phone | `+00000000002` | Using this phone number for the request always generates an `optout` response. | [POST&nbsp;/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&nbsp;/token/refresh](post-token-refresh.md) |
10 changes: 5 additions & 5 deletions docs/endpoints/post-token-refresh.md
Original file line number Diff line number Diff line change
Expand Up @@ -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&nbsp;/token/generate](post-token-generate.md) endpoint.

Used by: This endpoint is used mainly by publishers.

Expand All @@ -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&nbsp;/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&nbsp;/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

Expand All @@ -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&nbsp;/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
Expand Down Expand Up @@ -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&nbsp;/token/refresh](post-token-refresh.md) request for response decryption. |

### Response Status Codes

Expand Down
6 changes: 3 additions & 3 deletions docs/endpoints/post-token-validate.md
Original file line number Diff line number Diff line change
Expand Up @@ -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&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`. |
Expand Down Expand Up @@ -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&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 /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. 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.

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.
Expand Down
12 changes: 6 additions & 6 deletions docs/endpoints/summary-endpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,24 +7,24 @@ sidebar_position: 01

# UID2 Endpoints

All UID2 endpoints require a client secret for encrypting API requests (except [POST /token/refresh](post-token-refresh.md) requests) and decrypting responses. For details and Python script examples, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
All UID2 endpoints require a client secret for encrypting API requests (except [POST&nbsp;/token/refresh](post-token-refresh.md) requests) and decrypting responses. For details and Python script examples, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).

## UID2 Tokens

The following endpoints are for retrieving and managing UID2 tokens (identity tokens, advertising tokens), and are used mainly by publishers.

| Endpoint | Description | Request Encryption | Response Decryption |
| :--- | :--- | :--- | :--- |
| [POST /token/generate](post-token-generate.md) | Requests a UID2 token from an email address or phone number provided by a user with their authorization for UID2-based targeted advertising. If the DII is valid, and the user has not opted out of UID2, this operation returns a UID2 token and associated values. | Required | Required |
| [POST /token/validate](post-token-validate.md) | Used for testing, to validate that an advertising token (UID2) matches the specified email address, phone number, or the respective hash. | Required | Required |
| [POST /token/refresh](post-token-refresh.md) | Generate a new token for a user for their refresh token from the [POST /token/generate](post-token-generate.md) response. | N/A | Required |
| [POST&nbsp;/token/generate](post-token-generate.md) | Requests a UID2 token from an email address or phone number provided by a user with their authorization for UID2-based targeted advertising. If the DII is valid, and the user has not opted out of UID2, this operation returns a UID2 token and associated values. | Required | Required |
| [POST&nbsp;/token/validate](post-token-validate.md) | Used for testing, to validate that an advertising token (UID2) matches the specified email address, phone number, or the respective hash. | Required | Required |
| [POST&nbsp;/token/refresh](post-token-refresh.md) | Generate a new token for a user for their refresh token from the [POST&nbsp;/token/generate](post-token-generate.md) response. | N/A | Required |

## Identity Maps

The following endpoints are used by advertisers and third-party data providers. Publishers do not need to use these endpoints.

| Endpoint | Description | Request Encryption | Response Decryption |
| :--- | :--- | :--- | :--- |
| [POST /identity/buckets](post-identity-buckets.md) | Monitor rotated salt buckets using their last updated timestamp. | Required | Required |
| [POST /identity/map](post-identity-map.md) | Retrieve UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required |
| [POST&nbsp;/identity/buckets](post-identity-buckets.md) | Monitor rotated salt buckets using their last updated timestamp. | Required | Required |
| [POST&nbsp;/identity/map](post-identity-map.md) | Retrieve UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required |

2 changes: 1 addition & 1 deletion docs/getting-started/gs-auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,4 @@ To authenticate to the UID2 endpoints in a server-side implementation, you need

- A client [API key](gs-credentials.md#api-key-and-client-secret). The API key is included as a bearer token in the request's Authorization header. For example:<br/>
`Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=`
- A client secret for encrypting API requests and decrypting API responses. This is needed for all endpoints except [POST /token/refresh](../endpoints/post-token-refresh.md). <br/>For details and Python examples, see [Encrypting Requests and Decrypting Responses](gs-encryption-decryption.md).
- A client secret for encrypting API requests and decrypting API responses. This is needed for all endpoints except [POST&nbsp;/token/refresh](../endpoints/post-token-refresh.md). <br/>For details and Python examples, see [Encrypting Requests and Decrypting Responses](gs-encryption-decryption.md).
2 changes: 1 addition & 1 deletion docs/getting-started/gs-credentials.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Each UID2 <a href="/docs/intro#participants">participant</a> gets a set of uniqu

| Audience | Credentials | Integration |
| :--- | :--- | :--- |
| Participants using a server-side endpoint | Both of the following:<ul><li>[API key](../ref-info/glossary-uid.md#gl-api-key), also called a client key</li><li>[Client secret](../ref-info/glossary-uid.md#gl-client-secret), a value known only to the participant and the UID2 service</li></ul> | Any integration using one of these endpoints: <ul><li>[POST /identity/map](../endpoints/post-identity-map.md)</li><li>[POST /identity/buckets](../endpoints/post-identity-buckets.md)</li><li>[POST /token/generate](../endpoints/post-token-generate.md)</li></ul> |
| Participants using a server-side endpoint | Both of the following:<ul><li>[API key](../ref-info/glossary-uid.md#gl-api-key), also called a client key</li><li>[Client secret](../ref-info/glossary-uid.md#gl-client-secret), a value known only to the participant and the UID2 service</li></ul> | Any integration using one of these endpoints: <ul><li>[POST&nbsp;/identity/map](../endpoints/post-identity-map.md)</li><li>[POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md)</li><li>[POST&nbsp;/token/generate](../endpoints/post-token-generate.md)</li></ul> |
| Participants using a client-side implementation | Both of the following: <ul><li>Subscription ID</li><li>Public key</li></ul> | Integrations using one of these: <ul><li>[UID2 Client-Side Integration Guide for Prebid.js](../guides/integration-prebid-client-side.md)</li><li>[JavaScript Express Integration Guide](../guides/publisher-client-side.md)</li></ul> |

If you're using the integration environment as well as the production environment, you'll get a separate set of credentials for each environment.
Expand Down
6 changes: 3 additions & 3 deletions docs/getting-started/gs-encryption-decryption.md
Original file line number Diff line number Diff line change
Expand Up @@ -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&nbsp;/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:

Expand Down Expand Up @@ -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&nbsp;/token/generate](../endpoints/post-token-generate.md) request for an email address in the [preceding example](#request-example), may look like this:

```json
{
Expand All @@ -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&nbsp;/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&nbsp;/token/generate](../endpoints/post-token-generate.md) or [POST&nbsp;/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]"}`.
Expand Down
Loading

0 comments on commit bdadbae

Please sign in to comment.