Merge pull request #820 from IABTechLab/gwh-APIDOCS-2828-integ-guides-portal-instructions

all guides: update instructions re UID2 Portal

Author: genwhittTTD

docs/endpoints/post-identity-buckets.md

@@ -30,7 +30,7 @@ You must encrypt all requests using your secret. For details, and code examples
 | `{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>.
+The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials).
 :::
 
 ### Unencrypted JSON Body Parameters

docs/endpoints/post-identity-map.md

@@ -41,7 +41,7 @@ You must encrypt all requests using your secret. For details, and code examples
 | `{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>.
+The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials).
 :::
 
 ### Unencrypted JSON Body Parameters

docs/endpoints/post-optout-status.md

@@ -43,7 +43,7 @@ You must encrypt all requests using your secret. For details, and code examples
 | `{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>.
+The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials).
 :::
 
 ### Unencrypted JSON Body Parameters

docs/endpoints/post-token-validate.md

@@ -34,7 +34,7 @@ You must encrypt all requests using your secret key. For details, and code examp
 | `{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>.
+The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials).
 :::
 
 ### Unencrypted JSON Body Parameters

docs/getting-started/gs-account-setup.md

@@ -31,10 +31,13 @@ Contacting The Trade Desk for access is temporary. When the system is moved to i
 When you've expressed interest in UID2, someone will contact you to help work out the details.
 
 As part of account setup, provide the following information:
-* Name
-* Email address
-* Company name
-* Name and contact information for an authorized individual who can sign the contract.
+
+* Company name: The legal company name to be used in the UID2 contract.
+
+* A primary contact person. This individual becomes the primary administrator for the account. Include these values:
+  * Name
+  * Email address
+  * Job title
 
 ### Client-Side Web Integrations
 

docs/getting-started/gs-credentials.md

@@ -9,15 +9,72 @@ import Link from '@docusaurus/Link';
 
 # UID2 Credentials
 
-Each UID2 <a href="../intro#participants">participant</a> gets a set of unique credentials. The set of credentials you get is determined by how you are participating in UID2, as shown in the following table.
+Each UID2 <a href="../intro#participants">participant</a> needs at least one set of unique credentials. The set of credentials you need is determined by how you are participating in UID2, as shown in the following table.
 
 | Audience | Credentials | Integration |
 | :--- | :--- | :--- |
 | Participants using a client-side implementation | Both of the following: <ul><li><Link href="../ref-info/glossary-uid#gl-subscription-id">Subscription ID</Link></li><li><Link href="../ref-info/glossary-uid#gl-public-key">Public key</Link></li></ul>These two, together, are sometimes called <Link href="../ref-info/glossary-uid#gl-client-keypair">client keypair</Link>. | Integrations using one of these: <ul><li>[UID2 Client-Side Integration Guide for Prebid.js](../guides/integration-prebid-client-side.md)</li><li>[Client-Side Integration Guide for JavaScript](../guides/integration-javascript-client-side.md)</li><li>[UID2 Client-Side Integration Guide for Mobile](../guides/integration-mobile-client-side.md)</li></ul> |
 | Participants using a client-server implementation | Both of the following:<ul><li><Link href="../ref-info/glossary-uid#gl-api-key">API key</Link>, also called a client key</li><li><Link href="../ref-info/glossary-uid#gl-client-secret">Client secret</Link>, a value known only to the participant and the UID2 service</li></ul> | Integrations using one of these: <ul><li>[Client-Server Integration Guide for JavaScript](../guides/integration-javascript-client-server.md)</li><li>[UID2 Client-Server Integration Guide for Prebid.js](../guides/integration-prebid-client-server.md)</li><li>[UID2 Client-Server Integration Guide for Mobile](../guides/integration-mobile-client-server.md)</li></ul> |
 | Participants using a server-side implementation | Both of the following:<ul><li><Link href="../ref-info/glossary-uid#gl-api-key">API key</Link>, also called a client key</li><li><Link href="../ref-info/glossary-uid#gl-client-secret">Client secret</Link>, a value known only to the participant and the UID2 service</li></ul> | Integrations using one of these: <ul><li>[Publisher Integration Guide, Server-Side](../guides/integration-publisher-server-side.md)</li><li>[Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.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.
+## Separate Credentials Per Environment/Role
+
+If you're using the integration <Link href="../ref-info/glossary-uid#gl-environment">environment</Link> as well as the production environment, you'll get a separate set of credentials for each environment. See [Getting Your Credentials](#getting-your-credentials).
+
+In addition, in some cases, we recommend, but do not require, that you have a different set of credentials for a different scenario. For example:
+- If you're a publisher who generates UID2 tokens (via [POST /token/generate](../endpoints/post-token-generate.md) or in some other way), but you also create/map raw UID2s on your own behalf (see [POST /identity/map](../endpoints/post-identity-map.md)), you might have separate credentials for each of these activities.
+- If you're an advertiser, in a scenario where you allow multiple service providers to operate using your advertiser keys, you might choose to have separate credentials for each service provider.
+
+## Getting Your Credentials
+
+The following table shows how you get your credentials, for each [integration approach](../ref-info/ref-integration-approaches.md) and each [environment](../getting-started/gs-environments.md).
+
+<table>
+  <thead>
+    <tr>
+      <th>Environment</th>
+      <th>Integration Type</th>
+      <th>Getting Credentials</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td rowspan="3"><br/><br/>Prod</td>
+      <td>Client-Side</td>
+      <td>UID2 Portal > [Client-Side Integration](../portal/client-side-integration.md)</td>
+    </tr>
+    <tr>
+
+      <td>Client-Server</td>
+      <td>UID2 Portal > [API Keys](../portal/api-keys.md)</td>
+    </tr>
+    <tr>
+
+      <td>Server-Side</td>
+      <td>UID2 Portal > [API Keys](../portal/api-keys.md)</td>
+    </tr>
+    <tr>
+      <td rowspan="3"><br/><br/>Integ</td>
+      <td>Client-Side</td>
+      <td rowspan="3"><br/><br/>Ask your UID2 contact.</td>
+    </tr>
+    <tr>
+
+      <td>Client-Server</td>
+
+    </tr>
+    <tr>
+
+      <td>Server-Side</td>
+
+    </tr>
+  </tbody>
+</table>
+
+<!-- 
+For no-portal:
+To get your credentials, ask your UID2 contact.
+-->
 
 ## Subscription ID and Public Key
 
@@ -33,7 +90,7 @@ Notes:
 
 - Unlike the API key and client secret, the Subscription ID and public key do not have to be kept secure.
 
-- The values are valid for a specific [environment](gs-environments.md). If you're using both the integration and production environments, you'll get a set of credentials for each environment.
+- The values are valid for a specific environment. If you're using both the integration and production environments, you'll get a set of credentials for each environment.
 
 - Subscription ID and public key credentials can be used only to generate client-side tokens. If you need any additional roles (see [API Permissions](gs-permissions.md)), request API Key and Client Secret for those roles.
 
@@ -47,7 +104,7 @@ Here is some information about API keys and client secrets:
 - Each key has a set of [permissions](gs-permissions.md) that determine the endpoints you can use it on.
 - Each key has a corresponding client secret.
 - Most API endpoints require both API key and client secret for authentication. For details, see [Authentication and Authorization](gs-auth.md).
-- If you're using the integration environment as well as the production environment, you'll receive separate API keys for each environment.
+- If you're using the integration environment as well as the production environment, you'll receive separate API keys for each environment. For details, see [Getting Your Credentials](#getting-your-credentials).
 - The client secret is valid for a specific [environment](gs-environments.md). If you're using both the integration and production environments, you'll get a client secret for each environment.
 
 As part of getting your UID2 account set up, we'll give you one or more API keys, each with a corresponding client secret. For details of who to talk to, see [Contact Info](gs-account-setup.md#contact-info).
@@ -64,4 +121,12 @@ It's best to refresh your API key and client secret on a regular cadence&#8212;f
 
 ## Refreshing Credentials
 
-To request new credentials at any time, ask your UID2 contact.
+To request new credentials at any time, do one of the following:
+
+- If you have UID2 Portal access, and you need new Production credentials: go to the page listed in [Getting Your Credentials](#getting-your-credentials).
+- If you don't have UID2 Portal access, or you need new credentials for the Integration environment, ask your UID2 contact.
+
+<!-- 
+For no-portal:
+To request new credentials at any time, ask your UID2 contact. 
+-->

docs/getting-started/gs-environments.md

@@ -11,13 +11,13 @@ import Link from '@docusaurus/Link';
 
 Learn about the different environments available, and tips to reduce latency by choosing the best base URL for your integration.
 
-## UID2 Testing and Production Environments
+## UID2 Integration and Production Environments
 
-The following table lists all current testing and production environments for UID2.
+The following table lists all current integration (also known as testing) and production environments for UID2.
 
 | Environment | Cloud Region | Code | Base URL |
 | :--- | :--- | :--- | :--- |
-| Integration Testing | AWS US East (Ohio) | `us-east-2` | `https://operator-integ.uidapi.com` |
+| Integration (for testing) | AWS US East (Ohio) | `us-east-2` | `https://operator-integ.uidapi.com` |
 | Production | Automatically optimized region routing via the <a href='https://aws.amazon.com/global-accelerator/'>AWS Global Accelerator</a> | `n/a` | `https://global.prod.uidapi.com` |
 | Production | AWS US East (Ohio) | `us-east-2` | `https://prod.uidapi.com` |
 | Production | AWS US West (Oregon) | `us-west-2` | `https://usw.prod.uidapi.com` |
@@ -30,9 +30,15 @@ For example, `https://operator-integ.uidapi.com/v2/token/generate`.
 Notes:
 
 - All UID2 endpoints use the same base URL.
-- The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>.
+- The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials).
 - The expiration time of the <Link href="../ref-info/glossary-uid#gl-uid2-token">UID2 token</Link> returned by the [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) or [POST&nbsp;/token/refresh](../endpoints/post-token-refresh.md) endpoints is subject to change, but is always significantly shorter in the integration environment than it is in the production environment.
 
+## Getting Credentials for Each Environment
+
+If you're using the integration environment as well as the production environment, you'll need to get a separate set of credentials for each environment.
+
+For details about getting the values you need to access each environment, see [Getting Your Credentials](gs-credentials.md#getting-your-credentials).
+
 ## Specifying the Base URL to Reduce Latency
 
 The latency of API calls depends on the proximity of the client to the UID2 servers. To reduce the latency, especially when making API calls from consumer devices, you might consider choosing a server closer to your users.

docs/guides/integration-advertiser-dataprovider-endpoints.md

@@ -16,6 +16,21 @@ This guide covers integration steps for advertisers and data providers to integr
 For a summary of all integration options and steps for advertisers and data providers, see [Advertiser/Data Provider Integration Overview](integration-advertiser-dataprovider-overview.md).
 :::
 
+## Complete UID2 Account Setup and Configure Account
+
+To integrate with UID2, you'll need to have a UID2 account. If you haven't yet created an account, first follow the steps described on the [Account Setup](../getting-started/gs-account-setup.md) page.
+
+When initial account setup is complete, you'll receive instructions and a link to access the [UID2 Portal](../portal/portal-overview.md), where you can create your [credentials](../getting-started/gs-credentials.md) for the production environment and configure additional values, if needed. For details, see [Getting Started with the UID2 Portal](../portal/portal-getting-started.md).
+
+You'll need to set up these values, in the UID2 Portal on the [API Keys](../portal/api-keys.md) page:
+
+- <Link href="../ref-info/glossary-uid#gl-api-key">API key</Link>, also called a client key
+- <Link href="../ref-info/glossary-uid#gl-client-secret">Client secret</Link>, a value known only to the participant and the UID2 service
+
+:::important
+It's very important that you keep these values secure. For details, see [Security of API Key and Client Secret](../getting-started/gs-credentials.md#security-of-api-key-and-client-secret).
+:::
+
 ## High-Level Steps
 
 At a high level, the steps for advertisers and data providers integrating with UID2 are as follows:

docs/guides/integration-ctv-guide.md

@@ -27,6 +27,26 @@ To determine how you'll implement these steps, choose from the [CTV Integration
 
 <IntegratingWithSSO />
 
+## Complete UID2 Account Setup and Configure Account
+
+To integrate with UID2, you'll need to have a UID2 account. If you haven't yet created an account, first follow the steps described on the [Account Setup](../getting-started/gs-account-setup.md) page.
+
+When initial account setup is complete, you'll receive instructions and a link to access the [UID2 Portal](../portal/portal-overview.md), where you can create your [credentials](../getting-started/gs-credentials.md) for the production environment and configure additional values, if needed. For details, see [Getting Started with the UID2 Portal](../portal/portal-getting-started.md).
+
+The specific values you set up will depend on which of the [CTV integration options](#ctv-integration-options) you choose:
+
+- For a client-server or server-side implementation, you'll need to set up these values, in the UID2 Portal on the [API Keys](../portal/api-keys.md) page:
+  - <Link href="../ref-info/glossary-uid#gl-api-key">API key</Link>, also called a client key
+  - <Link href="../ref-info/glossary-uid#gl-client-secret">Client secret</Link>, a value known only to the participant and the UID2 service
+
+    :::important
+    It's very important that you keep these values secure. For details, see [Security of API Key and Client Secret](../getting-started/gs-credentials.md#security-of-api-key-and-client-secret).
+    :::
+- For a client-side implementation, you'll need to set up these values, in the UID2 Portal on the [Client-Side Integration](../portal/client-side-integration.md) page:
+  - Subscription ID and Public Key: See [Adding and Managing Key Pairs](../portal/client-side-integration.md#adding-and-managing-key-pairs)
+  - A list of **domain names** for any sites on which you'll be using this SDK: See [Adding and Managing Root-Level Domains](../portal/client-side-integration.md#adding-and-managing-root-level-domains)
+  - Mobile App IDs (any that apply): See [Adding and Managing Mobile App IDs](../portal/client-side-integration.md#adding-and-managing-mobile-app-ids)
+
 ## CTV Integration Options
 
 You can decide on the integration option that's best for you based on where you want to generate and refresh the UID2 token. There are three options, as follows:
@@ -35,7 +55,7 @@ You can decide on the integration option that's best for you based on where you
 - [Server-Side Integration](#server-side-integration-for-ctv-apps) (the token is generated and refreshed on the server side)
 - [Client-Server Integration](#client-server-integration-for-ctv-apps) (the token is generated on the server side and refreshed on the client side)
 
-## Client-Side Integration for CTV Apps
+### Client-Side Integration for CTV Apps
 
 The client-side option is for publishers who want to manage the UID2 token entirely on the client side:
 
@@ -53,7 +73,7 @@ The following table shows supported operating systems, with links to applicable
 | [Apple tvOS](https://developer.apple.com/tvos/) | [UID2 Client-Side Integration Guide for Mobile](../guides/integration-mobile-client-side.md) | [SDK for iOS Reference Guide](../sdks/sdk-ref-ios.md) |
 | [Android TV](https://www.android.com/tv/) | [UID2 Client-Side Integration Guide for Mobile](../guides/integration-mobile-client-side.md) | [SDK for Android Reference Guide](../sdks/sdk-ref-android.md) |
 
-## Server-Side Integration for CTV Apps
+### Server-Side Integration for CTV Apps
 
 The server-side option is for publishers who want to manage the UID2 token entirely on the server side:
 
@@ -71,7 +91,7 @@ If your server-side code is in Java or Python, you can use one of the UID2 SDKs
 - [SDK for Java Reference Guide: Usage for Publishers](../sdks/sdk-ref-java.md#usage-for-publishers)
 - [SDK for Python Reference Guide: Usage for Publishers](../sdks/sdk-ref-python.md#usage-for-publishers)
 
-## Client-Server Integration for CTV Apps
+### Client-Server Integration for CTV Apps
 
 This option is for publishers who want to manage the UID2 tokens with a client-server approach: