Merge main branch

Author: miyaichi

.github/workflows/deploy.yml

@@ -24,21 +24,21 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+        uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           cache: npm
       - name: Install dependencies
         run: npm ci
       - name: Build website
         run: npm run build
       - name: Setup Pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@v5
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
         with:
           path: './build'
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

.github/workflows/deployPreview.yml

@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Clone to preview folder (excluding actions)
         run: rsync -arv --delete --delete-excluded --exclude=".github" --exclude="preview-output" --exclude="preview-output" --exclude=".git" ./ preview-output/
       - name: Push to staging repository
@@ -35,4 +35,4 @@ jobs:
             destination-github-username: 'UnifiedID2'
             destination-repository-name: 'uid2-docs-preview'
             target-branch: main
-            target-directory: preview
+            target-directory: preview

.github/workflows/test.yml

@@ -13,14 +13,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+        uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           cache: npm
       - name: Install dependencies
         run: npm ci
       - name: Build website
         run: npm run build
       - name: Vulnerability Scan
-        uses: IABTechLab/uid2-shared-actions/actions/vulnerability_scan_filesystem@v2
+        uses: IABTechLab/uid2-shared-actions/actions/vulnerability_scan_filesystem@v3

docs/endpoints/post-identity-buckets.md

@@ -17,6 +17,8 @@ Used by: This endpoint is used mainly by advertisers and data providers. For det
 
 `POST '{environment}/v2/identity/buckets'`
 
+For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md).
+
 :::important
 You must encrypt all requests using your secret. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
 :::
@@ -25,7 +27,7 @@ You must encrypt all requests using your secret. For details, and code examples
 
 | Path Parameter | Data Type | Attribute | Description |
 | :--- | :--- | :--- | :--- |
-| `{environment}` | string | Required | Integration environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |
+| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |
 
 :::note
 The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>.

docs/endpoints/post-identity-map.md

@@ -13,6 +13,8 @@ Maps multiple email addresses, phone numbers, or their respective hashes to thei
 
 Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md).
 
+For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md).
+
 ## Batch Size and Request Parallelization Requirements
 
 Here's what you need to know:
@@ -26,6 +28,8 @@ Here's what you need to know:
 
 `POST '{environment}/v2/identity/map'`
 
+For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md).
+
 :::important
 You must encrypt all requests using your secret. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
 :::
@@ -34,7 +38,7 @@ You must encrypt all requests using your secret. For details, and code examples
 
 | Path Parameter | Data Type | Attribute | Description |
 | :--- | :--- | :--- | :--- |
-| `{environment}` | string | Required | Integration environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |
+| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |
 
 :::note
 The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>.
@@ -93,7 +97,7 @@ The following are unencrypted JSON request body examples for each parameter, one
 Here's an encrypted identity mapping request example for a phone number:
 
 ```sh
-echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk= DELPabG/hsJsZk4Xm9Xr10Wb8qoKarg4ochUdY9e+Ow=
+echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret]
 ```
 
 For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).

docs/endpoints/post-optout-status.md

@@ -30,6 +30,8 @@ The key guidelines for managing batches of requests to this endpoint are as foll
 
 `POST '{environment}/v2/optout/status'`
 
+For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md).
+
 :::important
 You must encrypt all requests using your secret. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
 :::
@@ -38,7 +40,7 @@ You must encrypt all requests using your secret. For details, and code examples
 
 | Path Parameter | Data Type | Attribute | Description |
 | :--- | :--- | :--- | :--- |
-| `{environment}` | string | Required | Integration environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |
+| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |
 
 :::note
 The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>.

docs/endpoints/post-token-generate.md

@@ -26,7 +26,9 @@ Rather than calling this endpoint directly, you could use one of the SDKs to man
 
 `POST '{environment}/v2/token/generate'`
 
-Here's what you need to know about this endpoint requests:
+For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md).
+
+Here's what you need to know about sending requests to this endpoint:
 - To ensure that the <Link href="../ref-info/glossary-uid#gl-api-key">API key</Link> used to access the service remains secret, UID2 tokens must be generated only on the server side after authentication. 
 - You must encrypt all requests using your secret. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
 
@@ -53,7 +55,7 @@ You must include only **one** of the following four conditional parameters, plus
 ### 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&nbsp;/token/refresh](post-token-refresh.md), which does not require using an API key.
+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 [POST&nbsp;/token/refresh](post-token-refresh.md) which does not require using an API key. If you want to generate tokens on the client side, see [Client-Side Integration Options](../guides/integration-options-publisher-web.md#client-side-integration-options) (for web-based implementations) or [UID2 Client-Side Integration Guide for Mobile](../guides/integration-mobile-client-side.md).
 :::
 
 The following are unencrypted JSON request body examples for each parameter, one of which you should include in your token generation requests:
@@ -103,7 +105,7 @@ This section includes the following sample responses:
 
 #### Successful Response
 
-A successful decrypted response returns the user's advertising and refresh tokens for the specified email address, phone number, or the respective hash. 
+A successful decrypted response returns the user's advertising and refresh tokens for the specified email address, phone number, or the respective hash.
 
 <IdentityGenerateResponse />
 
@@ -145,8 +147,8 @@ If the `status` value is anything other than `success`, the `message` field prov
 
 ## Test Identities
 
-| Type  | Identity                     | Purpose                                                                                                                                    | Next Endpoint                                  |
-|:------|:-----------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------|
+| 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&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)   |

docs/endpoints/post-token-refresh.md

@@ -37,7 +37,7 @@ Here's what you need to know about this endpoint:
 
 | Path Parameter | Data Type | Attribute | Description |
 | :--- | :--- | :--- | :--- |
-| `{environment}` | string | Required | Integration environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md).<br/>Notes:<ul><li>The `integ` environment and the `prod` environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>.</li><li>Token expiration time is subject to change, but is always significantly shorter in the `integ` environment than it is in the `prod` environment.</li></ul> |
+| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md).<br/>Notes:<ul><li>The `integ` environment and the `prod` environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>.</li><li>Token expiration time is subject to change, but is always significantly shorter in the `integ` environment than it is in the `prod` environment.</li></ul> |
 
 #### Testing Notes
 

docs/endpoints/post-token-validate.md

@@ -9,7 +9,7 @@ import Link from '@docusaurus/Link';
 
 # POST /token/validate
 
-Validates that an advertising token matches the specified hashed or unhashed email address or phone number. 
+Validates that an advertising token matches the specified hashed or unhashed email address or phone number.
 
 Used by: This endpoint is used mainly by publishers.
 
@@ -21,6 +21,8 @@ This endpoint is intended primarily for testing and troubleshooting new integrat
 
 `POST '{environment}/v2/token/validate'`
 
+For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md).
+
 :::important
 You must encrypt all requests using your secret key. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
 :::
@@ -29,7 +31,7 @@ You must encrypt all requests using your secret key. For details, and code examp
 
 | Path Parameter | Data Type | Attribute | Description |
 | :--- | :--- | :--- | :--- |
-| `{environment}` | string | Required | Integration environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |
+| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |
 
 :::note
 The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>.

docs/endpoints/summary-endpoints.md

@@ -35,6 +35,8 @@ The following endpoints are used by advertisers and third-party data providers.
 
 The following endpoint can be used by advertisers, third-party data providers, DSPs, and sharers. Publishers do not need to use this endpoint.
 
+For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md).
+
 | Endpoint | Description | Request Encryption | Response Decryption |
 | :--- | :--- | :--- | :--- |
 | [POST /optout/status](post-optout-status.md) | Checks the opt-out status of raw UID2s. This endpoint takes a list of raw UID2s as input, and returns the raw UID2s that have opted out, as well as the time that the opt-out took place.  | Required | Required |