Account-scoped personal access tokens

website/docs/docs/dbt-cloud-apis/authentication.md

@@ -1,5 +1,5 @@
 ---
-title: "Authentication"
+title: "Authentication tokens"
 description: "Learn how to authenticate with user tokens and service account tokens "
 pagination_next: "docs/dbt-cloud-apis/user-tokens"
 pagination_prev: null
@@ -19,4 +19,21 @@ pagination_prev: null
     link="/docs/dbt-cloud-apis/service-tokens"
     icon="dbt-bit"/>
 
-</div>
+</div>
+
+## Types of API access tokens
+
+**User API keys (Legacy):** User API keys were historically the only method available to access dbt Cloud APIs on the user’s behalf. They are scoped to the user and not the account. User API Keys will eventually be deprecated for the more secure Personal Access Tokens.
+
+**Personal access tokens (New):** Personal access tokens (PATs) are the new, preferred, and secure way of accessing dbt Cloud APIs on behalf of a user. They are more secure than user API Keys. PATs are scoped to an account and can be enhanced with more granularity and control. 
+
+**Service tokens:** Service tokens are similar to service accounts and are the preferred method to enable access on behalf of the dbt Cloud account.
+
+### Which token type should you use
+
+The following use cases highlight scenarios where you should use a personal access token (PAT) vs. a service token. Service tokens are broadly used for any production workflow where service accounts are required. PATs are recommended only for developmental workflows _or_ dbt Cloud client workflows that require user context. 
+
+* **Connecting a partner integration to dbt Cloud** &mdash; Some examples are Hightouch, Datafold, a custom app you’ve created, etc. All of these integrations should use a service token instead of a PAT because service tokens give you visibility, and you can scope them specifically to only what the integrations need and ensure the least privilege. We highly recommend switching to a service token if you’re using a user API key for these today. 
+* **Production Terraform** &mdash; Use a service token since this is a production workflow and is acting as a service account and not a user account. 
+* **Cloud CLI and Semantic Layer Sheets Integration** &mdash; Use a PAT since both the dbt Cloud CLI and Semantic Layer Google Sheets integrations work within the context of a user (the user is making the requests and has to operate within the context of their user account).
+* **Testing a custom script and staging Terraform or Postman** &mdash; We recommend using a PAT as this is a developmental workflow and is scoped to the user making the changes. There are certain instances where you may need/require a service token. However, when you push this script or Terraform into production, use a service token instead.

website/docs/docs/dbt-cloud-apis/user-tokens.md

@@ -4,19 +4,72 @@ id: "user-tokens"
 pagination_next: "docs/dbt-cloud-apis/service-tokens"
 ---
 
+:::note Action required
+
+The [user API tokens](#user-tokens) will eventually be deprecated. The deprecation date is yet to be determined, but we recommend you update to account-scoped personal access tokens to avoid service disruptions in the future. We will communicate, with ample notice, the deprecation date when it has been determined.
+
+The current API key is located under **Personal Settings → API Key.** 
+
+Please [contact support](/docs/dbt-support#dbt-cloud-support) with any questions or concerns.
+
+:::
+
+## Account-scoped personal access tokens
+
+:::info New 
+
+On Feb 7, 2024, we introduced a new type of token for individual users called personal access tokens. Note that these differ from [Service Tokens or API Keys](/docs/dbt-cloud-apis/authentication#types-of-api-access-tokens). Before this release, user API keys were the only way to access dbt Cloud API on behalf of the user. These API Keys were user-specific and were not scoped to an account. To enhance the security of dbt Cloud, we are moving away from this model to account-specific tokens. 
+
+:::
+
+Each dbt Cloud user with a [Developer license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) can create a new personal access token (PAT) to access the dbt Cloud API and dbt Cloud CLI. This token can execute queries against the dbt Cloud API on the user's behalf. To access dbt Cloud APIs and resources on behalf of the _account_, we recommend using service Tokens instead. Learn more about [which token type you should use](/docs/dbt-cloud-apis/authentication#which-token-type-should-you-use) to understand the token differences.
+
+PATs inherit the permissions of the user that created them. For example, if a developer-licensed user with Project Admin role access to specific projects creates a PAT, the token will get the Project Admin role with access to the same projects as the user. These tokens are also account-specific, so if a user has access to more than one dbt Cloud account with the same email address, they need to create a unique PAT for each one of these accounts. 
+
+### Migrating from user API keys to personal access tokens
+
+This is critical if you’ve been using user API keys. Today, the current API key is located under **Personal Settings → API Key**
+
+ This has a few implications if you are using a user API key today: 
+
+* **Personal access tokens are more secure** 
+    * To promote least privPATs away from user API keys.
+* **You must create and use unique tokens in each one of your dbt Cloud accounts that are tied to the same email.** 
+    * For example, if [email protected] belongs to two dbt Cloud accounts: Spice Harvesting Account and Guild Navigator Account. Prior to this release, the same API key was used to access both of these accounts. 
+    * After this release, Paul has to individually go into these accounts and create a unique PAT for each account he wants to access the API for. These PATs are account-specific and not user specific. 
+* **Cross-Account API endpoints will change in behavior when using the personal access tokens**
+    * These are namely /v2/accounts and /v3/accounts. Since all PATs are now account specific, getting all accounts tied to a username cannot work. /v3/accounts will only return account metadata that’s relevant to the PAT that’s being used. 
+    * User account metadata will only contain information about the specific account under which the request is being made. 
+    * Any other accounts that belong to that user account will need to be requested through the PAT that belongs to that account. 
+
+:::warning Undocumented APIs
+
+If you’re using any undocumented and unsupported API endpoints, please note that these can be deprecated without any notice. If you are using any undocumented endpoints and have use-cases that are not satisfied by the current API, please reach out to [[email protected]](mailto:[email protected]). 
+
+:::
+
+### Using the new personal access tokens
+
+Are you using a user API key today to access dbt Cloud APIs in any of your workflows? If not, you don’t have any action to take. If you are using a user API key, please follow the instructions below. 
+
+1. Make a list of all the places where you’re making a call to the dbt Cloud API using the dbt Cloud user API key. 
+2. Create a new personal access token under **Account Settings → API Tokens → Personal Tokens.** 
+3. Create and copy the new PAT to replace the old user API key. 
+4. Ensure that you’re using a PAT only where its needed. For any flows that requires a service account, please use a service token. Read the section below for more information.
+
 ## User API tokens
 
 Each dbt Cloud user with a [Developer license](/docs/cloud/manage-access/seats-and-users) is
 issued an API token. This token can be used to execute queries against
 the dbt Cloud API on the user's behalf. User API tokens inherit the
 permissions of the user the that they were created for.
 
-You can find your User API token in the Profile page under the `API Access`
+You can find your user API token in the **Profile page** under the **API Access**
 label.
 
 <Lightbox src="/img/api-access-profile.jpg" title="Finding your API token in your dbt Cloud Profile" />
 
 ## FAQs
 
 <FAQ path="API/rotate-token" />
-<FAQ path="Accounts/find-user-id" />
+<FAQ path="Accounts/find-user-id" />

website/sidebars.js

@@ -500,7 +500,7 @@ const sidebarSettings = {
         "docs/dbt-cloud-apis/overview",
         {
           type: "category",
-          label: "Authentication",
+          label: "API Access",
           link: { type: "doc", id: "docs/dbt-cloud-apis/authentication" },
           items: [
             "docs/dbt-cloud-apis/authentication",