Merge pull request #737 from IABTechLab/gwh-APIDOCS-2683-pub-ov-add-t…

…oken-refresh

Token refresh, add to glossary + add links

docs/endpoints/post-token-refresh.md

@@ -28,7 +28,7 @@ Add the content of the `refresh_token` value, returned in the response from the
 
 Here's what you need to know about this endpoint:
 
-- No encryption is required for token refresh requests.
+- No encryption is required for requests to the `POST /token/refresh` endpoint.
 - 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.

docs/getting-started/gs-faqs.md

@@ -101,7 +101,7 @@ The recommended refresh interval is hourly.
 
 To determine when to refresh, you can use the timestamp of the `refresh_from` field in the response to the [POST /token/generate](../endpoints/post-token-generate.md) endpoint (see [Successful Response](../endpoints/post-token-generate.md#successful-response)) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint (see [Successful Response With Tokens](../endpoints/post-token-refresh.md#successful-response-with-tokens)).
 
-You could also use one of the SDKs that has a function to check if token refresh is needed.
+You could also use one of the SDKs that has a function to check if <a href="../ref-info/glossary-uid#gl-token-refresh">token refresh</a> is needed.
 
 For details, see [Recommended Token Refresh Frequency](../ref-info/ref-tokens.md#recommended-token-refresh-frequency) and [Managing Token Refresh with an SDK](../ref-info/ref-tokens.md#managing-token-refresh-with-an-sdk).
 

docs/guides/integration-javascript.md

@@ -42,7 +42,7 @@ From the table in [Client-Side or Client-Server Integration](#client-side-or-cli
 
 ## Refreshing the UID2 Token
 
-The SDK for JavaScript includes automated token refresh.
+The SDK for JavaScript includes automated <a href="../ref-info/glossary-uid#gl-token-refresh">token refresh</a>.
 
 ## Storing the UID2 Token in the Browser
 <!-- GWH check corresponding (not identical) section in integration-prebid.md, integration-prebid-client-side.md, integration-prebid-client-side.md, for consistency -->

docs/guides/integration-mobile-client-server.md

@@ -85,7 +85,7 @@ For security reasons, the API key and secret used in token generation must be ca
 
 ## Server-Side Token Refresh
 
-Token refresh is automatically enabled inside the UID2 mobile SDKs; you don't need to manage it explicitly on the server side.
+<a href="../ref-info/glossary-uid#gl-token-refresh">Token refresh</a> is automatically enabled inside the UID2 mobile SDKs; you don't need to manage it explicitly on the server side.
 
 You might decide to do server-side token refresh if you want to keep your changes in the mobile apps as simple as possible.
 

docs/guides/integration-prebid-client-server.md

@@ -20,7 +20,7 @@ This is called client-server integration because some integration steps are clie
 To integrate with UID2 using Prebid.js, you'll need to:
 
 - Make changes to the HTML and JavaScript on your site.
-- Make server-side changes for token generation (and, optionally, token refresh).  
+- Make server-side changes for token generation (and, optionally, <a href="../ref-info/glossary-uid#gl-token-refresh">token refresh</a>).  
 
 ## Prebid.js Version
 This implementation requires Prebid.js version 7.53.0 or later. For version information, see [https://github.com/prebid/Prebid.js/releases](https://github.com/prebid/Prebid.js/releases).

docs/overviews/overview-publishers.md

@@ -105,7 +105,7 @@ For a detailed summary of web integration options, see [Web Integration Overview
 | Integration Type                     | Documentation                                                                                       | Content Description |
 |:-------------------------------------|:----------------------------------------------------------------------------------------------------| :--- |
 | Prebid (Overview)                    | [UID2 Integration Overview for Prebid](../guides/integration-prebid.md)                             | An overview of options for publishers who want to integrate with UID2 and generate UID2 tokens to be passed by Prebid.js or Prebid Mobile SDK in the RTB bidstream. |
-| Prebid.js Client-Side Integration    | [UID2 Client-Side Integration Guide for Prebid.js](../guides/integration-prebid-client-side.md)     | A guide for publishers who want to request UID2 tokens client-side, which is the easiest implementation approach, and choose to have Prebid.js manage the following: <ul><li>Token generation and token refresh.</li><li>Passing the tokens into the RTB bidstream.</li></ul> |
+| Prebid.js Client-Side Integration    | [UID2 Client-Side Integration Guide for Prebid.js](../guides/integration-prebid-client-side.md)     | A guide for publishers who want to request UID2 tokens client-side, which is the easiest implementation approach, and choose to have Prebid.js manage the following: <ul><li>Token generation and <a href="../ref-info/glossary-uid#gl-token-refresh">token refresh</a>.</li><li>Passing the tokens into the RTB bidstream.</li></ul> |
 | Prebid.js Client-Server Integration  | [UID2 Client-Server Integration Guide for Prebid.js](../guides/integration-prebid-client-server.md)   | A guide for publishers who want to integrate with UID2 and generate <Link href="../ref-info/glossary-uid#gl-uid2-token">UID2 tokens</Link> (advertising tokens) to be passed by Prebid.js in the RTB bidstream, but want to generate tokens server-side: for example, publishers who are using a <Link href="../ref-info/glossary-uid#gl-private-operator">Private Operator</Link>. |
 | JavaScript (Overview)                | [UID2 Integration Overview for JavaScript](../guides/integration-javascript.md)                     | An overview of options for publishers who want to integrate with UID2 using the JavaScript SDK. |
 | JavaScript Client-Side Integration   | [Client-Side Integration Guide for JavaScript](../guides/integration-javascript-client-side.md)     | A guide for publishers who want to integrate with UID2 using only client-side JavaScript changes, which is the easiest implementation approach.<br/>The SDK for JavaScript manages token generation and token refresh automatically. |

docs/ref-info/glossary-uid.md

@@ -99,6 +99,7 @@ import Link from '@docusaurus/Link';
 <a href="#gl-subscription-id">Subscription ID</a> 
 
 **T**
+<a href="#gl-tokenized-refresh">Tokenrefresh</a> | 
 <a href="#gl-tokenized-sharing">Tokenized sharing</a> | 
 <a href="#gl-transparency-and-control-portal">Transparency and Control Portal</a> 
 
@@ -433,6 +434,13 @@ import Link from '@docusaurus/Link';
 
 <dl>
 
+<dt><MdxJumpAnchor id="gl-token-refresh"><a href="#gl-token-refresh">Token refresh</a></MdxJumpAnchor></dt>
+<dd>When a UID2 participant requests a <a href="#gl-uid2-token">UID2 token</a>, the token is returned with a set of associated values, including a <a href="#gl-refresh-token">refresh token</a> and timestamps for the UID2 token and the refresh token. As long as the refresh token has not expired, the publisher can use it to request a fresh UID2 token without having to send <a href="#gl-dii">DII</a>.</dd>
+<dd>Any UID2 participant that requests a UID2 token must have a process in place for keeping the token valid: either monitoring the refresh period and requesting a new UID2 token before the refresh token expires, or requesting a new UID2 token each time, which requires sending DII.</dd>
+<dd>In most cases, token refresh is managed by an SDK or other implementation strategy such as a Prebid.js implementation.</dd>
+<dd>If the refresh token expires, the publisher must re-request a UID2 token by sending DII.</dd>
+<dd>For details, see <a href="ref-tokens">UID2 Tokens and Refresh Tokens</a>.</dd>
+
 <dt><MdxJumpAnchor id="gl-tokenized-sharing"><a href="#gl-tokenized-sharing">Tokenized sharing</a></MdxJumpAnchor></dt>
 <dd>Tokenized sharing means encrypting <a href="#gl-dii">DII</a> or <a href="#gl-raw-uid2">Raw UID2s</a> into <a href="#gl-uid2-token">UID2 tokens</a> and sharing the tokens with authorized recipients. Using UID2 tokens helps protect raw UID2s end-to-end between the sender and receiver of the data, including when the data passes through unauthorized parties. Tokenized sharing is required for sharing in the bidstream or via pixels, but you can use it in any sharing use case.</dd>
 <dd>For details, see <a href="../sharing/sharing-tokenized-overview">Tokenized Sharing Overview</a>.</dd>
@@ -474,7 +482,7 @@ import Link from '@docusaurus/Link';
 <dd>The token value is opaque: No assumptions should be made about the format or about the length of the string.</dd>
 <dd>The token has a limited life, but can be refreshed in the background using the <a href="#gl-refresh-token">refresh token</a>.</dd>
 <dd>Publishers send UID2 tokens in the bidstream.</dd>
-<dd>For details, see <a href="../intro#uid2-identifier-types">UID2 Identifier Types</a>.</dd>
+<dd>For details, see <a href="../intro#uid2-identifier-types">UID2 Identifier Types</a> and <a href="ref-tokens#uid2-tokens-key-information">UID2 Tokens: Key Information</a>.</dd>
 
 <dt><MdxJumpAnchor id="gl-unified-id-20"><a href="#gl-unified-id-20">Unified ID 2.0</a></MdxJumpAnchor></dt>
 <dd>The term UID2 can be used to mean the <a href="#gl-uid2-framework">UID2 framework</a>, the <a href="#gl-uid2-service">UID2 service</a>, a <a href="#gl-raw-uid2">raw UID2</a>, or a <a href="#gl-uid2-token">UID2 token</a> (advertising token).</dd>

docs/ref-info/ref-tokens.md

@@ -37,7 +37,7 @@ Here are some key points about refresh tokens:
 - The token value is an <a href="glossary-uid#gl-opaque">opaque</a> string: do not make any assumptions about the format or length of the string.
 - You can use the refresh token to generate a new UID2 token and new refresh token before the current refresh token expires.
 - Using refresh tokens is optional: you could choose to generate a new token from DII each time rather than refreshing an existing token. 
-- You can manage token refresh in a variety of ways, such as:
+- You can manage <a href="../ref-info/glossary-uid#gl-token-refresh">token refresh</a> in a variety of ways, such as:
   - With a UID2 SDK (see [SDK Functionality](../sdks/summary-sdks.md#sdk-functionality))
   - By calling the [POST&nbsp;/token/refresh](../endpoints/post-token-refresh.md) endpoint
   - By using the UID2 Prebid.js module (see [UID2 Integration Overview for Prebid.js](../guides/integration-prebid.md))

docs/sdks/sdk-ref-javascript-v2.md

@@ -103,8 +103,7 @@ As part of the SDK [initialization](#initopts-object-void), a token auto-refresh
 
 Here's what you need to know about the token auto-refresh:
 
-
-- Only one token refresh call can be active at a time. 
+- Only one call to the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint call can be active at a time. 
 - If the [POST /token/refresh](../endpoints/post-token-refresh.md) response is unsuccessful because the user has opted out, or because the refresh token has expired, this suspends the background auto-refresh process. To use UID2-based targeted advertising again, you must obtain the email or phone number from the consumer ([isLoginRequired()](#isloginrequired-boolean) returns `true`). In all other cases, auto-refresh attempts continue in the background.
 - The [callback function](#callback-function) specified during the SDK initialization is invoked in the following cases:
 	- After each successful refresh attempt.