From 2189a267eeae115fe179745711fec05db2d530b9 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Thu, 25 Jan 2024 16:05:59 -0500 Subject: [PATCH 01/11] Account-scoped personal access tokens --- .../dbt-cloud-apis/personal-access-tokens.md | 54 +++++++++++++++++++ .../docs/docs/dbt-cloud-apis/user-tokens.md | 8 +++ website/sidebars.js | 1 + 3 files changed, 63 insertions(+) create mode 100644 website/docs/docs/dbt-cloud-apis/personal-access-tokens.md diff --git a/website/docs/docs/dbt-cloud-apis/personal-access-tokens.md b/website/docs/docs/dbt-cloud-apis/personal-access-tokens.md new file mode 100644 index 00000000000..b389391b7dc --- /dev/null +++ b/website/docs/docs/dbt-cloud-apis/personal-access-tokens.md @@ -0,0 +1,54 @@ +--- +title: "Account-scoped personal access tokens" +id: "personal-access-tokens" +description: "Personal access tokens help you define permissions for securing access to your dbt Cloud account and its projects." +--- + +Each dbt Cloud user with a [developer license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) can create a personal access token (PAT) to access the dbt Cloud API. This token is used to execute queries against the dbt Cloud API on the user's behalf. User API tokens inherit the permissions of the user that they were created for. These tokens are account-specific; If a user has access to more than one dbt Cloud account with the same email address, you need to create a unique PAT for each one of these accounts. + +:::warning Action required + +On Jan X, 2024 the [user API tokens](/docs/dbt-cloud-apis/user-tokens) will be deprecated. You must update to account-scoped personal access tokens by March X, 2024 or you may experience service disruptions. + +The current API key is located under **Personal Settings → API Key.** + +::: + +On Jan X, 2024, all new personal API Access Tokens (PATs) created will be account-specific. PATs differ from [Service Tokens](/docs/dbt-cloud-apis/service-tokens), which remain unaffected by this change. Prior to this update, API keys were user-specific and, as such, were not scoped to an account. To enhance the security of dbt Cloud, we are moving away from this model to account-specific tokens. This has a few implications if you’re using a user token today: + +* **All existing API keys will stop working after April X, 2024:** + * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped personal access tokens. +* **You must create and implement unique tokens in each of your dbt Cloud accounts associated with the same email:** + * For example, paul@atreides.com belongs to two dbt Cloud accounts: Spice Harvesting Account and Guild Navigator Account. Before this release, the same API key was used to access both 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. These API tokens are account-specific and not user-specific. +* **Cross-Account API endpoints will stop working after April X, 2024:** + * These are /v2/accounts and /v3/accounts. Since all tokens are now account-specific, tying all accounts to a username will not work. So /v3/accounts will be deprecated. + * Moving forward, dbt Cloud will no longer support this model. User account metadata will only contain information about the specific account under which the request is 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 API endpoints + +If you’re using any undocumented and unsupported API endpoints, please note that these can be deprecated without any notice. If you're using any undocumented endpoints and have use-cases that are not satisfied by the current API, please reach out to apifeedback@dbt.com. + +::: + +## Migration Checklist + +If you are not using a user API key to access dbt Cloud APIs, you do not need to take any action. If you are using a user API key, please read the following instructions: + +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 **Settings** → **Access Token** + * (Need screenshot) +3. Use this new PAT to replace the old user API key. +4. Ensure that you’re using a PAT only where it’s needed. For any workflows that require a service account, please use a [service token](/docs/dbt-cloud-apis/service-tokens). + + +## Service tokens vs. personal access token (PAT) + +The following use cases highlight scenarios where you should use a 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** — Examples here are Hightouch, Datafold, a custom app you’ve created, etc. All of these integrations should use a service token instead of a PAT. This is because service tokens give you visibility, and you can scope them specifically to only what the integrations need and ensure the least privilege. If you’re using a user API key for these today, we highly recommend that you switch to a service token. +* **Production Terraform** — 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** — 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** — 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. \ No newline at end of file diff --git a/website/docs/docs/dbt-cloud-apis/user-tokens.md b/website/docs/docs/dbt-cloud-apis/user-tokens.md index 77e536b12a5..be9855ae17f 100644 --- a/website/docs/docs/dbt-cloud-apis/user-tokens.md +++ b/website/docs/docs/dbt-cloud-apis/user-tokens.md @@ -4,6 +4,14 @@ id: "user-tokens" pagination_next: "docs/dbt-cloud-apis/service-tokens" --- +:::warning + +Personal API Keys are being deprecated. Please create a new account-scoped API token (under account settings) and use that instead. Make this change before March X, 2024. Learn more about this change and the migration process on the [Personal Access Token](/docs/dbt-cloud-apis/personal-access-tokens) page. + +Please [contact support](/docs/dbt-support#dbt-cloud-support) with any questions or concerns. + +::: + ## User API tokens Each dbt Cloud user with a [Developer license](/docs/cloud/manage-access/seats-and-users) is diff --git a/website/sidebars.js b/website/sidebars.js index 0566ef8c3a6..b1f5ea1fe6f 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -504,6 +504,7 @@ const sidebarSettings = { link: { type: "doc", id: "docs/dbt-cloud-apis/authentication" }, items: [ "docs/dbt-cloud-apis/authentication", + "docs/dbt-cloud-apis/personal-access-tokens", "docs/dbt-cloud-apis/user-tokens", "docs/dbt-cloud-apis/service-tokens", ], From ef9018179c2c0a5f55761e2cf4593b3c48653232 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Fri, 2 Feb 2024 11:15:20 -0500 Subject: [PATCH 02/11] Updating based on feedback --- .../dbt-cloud-apis/personal-access-tokens.md | 54 ------------------ .../docs/docs/dbt-cloud-apis/user-tokens.md | 56 ++++++++++++++++++- website/sidebars.js | 1 - 3 files changed, 54 insertions(+), 57 deletions(-) delete mode 100644 website/docs/docs/dbt-cloud-apis/personal-access-tokens.md diff --git a/website/docs/docs/dbt-cloud-apis/personal-access-tokens.md b/website/docs/docs/dbt-cloud-apis/personal-access-tokens.md deleted file mode 100644 index b389391b7dc..00000000000 --- a/website/docs/docs/dbt-cloud-apis/personal-access-tokens.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Account-scoped personal access tokens" -id: "personal-access-tokens" -description: "Personal access tokens help you define permissions for securing access to your dbt Cloud account and its projects." ---- - -Each dbt Cloud user with a [developer license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) can create a personal access token (PAT) to access the dbt Cloud API. This token is used to execute queries against the dbt Cloud API on the user's behalf. User API tokens inherit the permissions of the user that they were created for. These tokens are account-specific; If a user has access to more than one dbt Cloud account with the same email address, you need to create a unique PAT for each one of these accounts. - -:::warning Action required - -On Jan X, 2024 the [user API tokens](/docs/dbt-cloud-apis/user-tokens) will be deprecated. You must update to account-scoped personal access tokens by March X, 2024 or you may experience service disruptions. - -The current API key is located under **Personal Settings → API Key.** - -::: - -On Jan X, 2024, all new personal API Access Tokens (PATs) created will be account-specific. PATs differ from [Service Tokens](/docs/dbt-cloud-apis/service-tokens), which remain unaffected by this change. Prior to this update, API keys were user-specific and, as such, were not scoped to an account. To enhance the security of dbt Cloud, we are moving away from this model to account-specific tokens. This has a few implications if you’re using a user token today: - -* **All existing API keys will stop working after April X, 2024:** - * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped personal access tokens. -* **You must create and implement unique tokens in each of your dbt Cloud accounts associated with the same email:** - * For example, paul@atreides.com belongs to two dbt Cloud accounts: Spice Harvesting Account and Guild Navigator Account. Before this release, the same API key was used to access both 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. These API tokens are account-specific and not user-specific. -* **Cross-Account API endpoints will stop working after April X, 2024:** - * These are /v2/accounts and /v3/accounts. Since all tokens are now account-specific, tying all accounts to a username will not work. So /v3/accounts will be deprecated. - * Moving forward, dbt Cloud will no longer support this model. User account metadata will only contain information about the specific account under which the request is 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 API endpoints - -If you’re using any undocumented and unsupported API endpoints, please note that these can be deprecated without any notice. If you're using any undocumented endpoints and have use-cases that are not satisfied by the current API, please reach out to apifeedback@dbt.com. - -::: - -## Migration Checklist - -If you are not using a user API key to access dbt Cloud APIs, you do not need to take any action. If you are using a user API key, please read the following instructions: - -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 **Settings** → **Access Token** - * (Need screenshot) -3. Use this new PAT to replace the old user API key. -4. Ensure that you’re using a PAT only where it’s needed. For any workflows that require a service account, please use a [service token](/docs/dbt-cloud-apis/service-tokens). - - -## Service tokens vs. personal access token (PAT) - -The following use cases highlight scenarios where you should use a 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** — Examples here are Hightouch, Datafold, a custom app you’ve created, etc. All of these integrations should use a service token instead of a PAT. This is because service tokens give you visibility, and you can scope them specifically to only what the integrations need and ensure the least privilege. If you’re using a user API key for these today, we highly recommend that you switch to a service token. -* **Production Terraform** — 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** — 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** — 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. \ No newline at end of file diff --git a/website/docs/docs/dbt-cloud-apis/user-tokens.md b/website/docs/docs/dbt-cloud-apis/user-tokens.md index be9855ae17f..429fc1a6a0a 100644 --- a/website/docs/docs/dbt-cloud-apis/user-tokens.md +++ b/website/docs/docs/dbt-cloud-apis/user-tokens.md @@ -6,7 +6,7 @@ pagination_next: "docs/dbt-cloud-apis/service-tokens" :::warning -Personal API Keys are being deprecated. Please create a new account-scoped API token (under account settings) and use that instead. Make this change before March X, 2024. Learn more about this change and the migration process on the [Personal Access Token](/docs/dbt-cloud-apis/personal-access-tokens) page. +Personal API Keys are being deprecated. Please create a new account-scoped API token (under account settings) and use that instead. Learn more about this change and the migration process on the [Personal Access Token](/docs/dbt-cloud-apis/personal-access-tokens) page. Please [contact support](/docs/dbt-support#dbt-cloud-support) with any questions or concerns. @@ -24,7 +24,59 @@ label. + +## Account-scoped personal access tokens + +Each dbt Cloud user with a [developer license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) can create a personal access token (PAT) to access the dbt Cloud API. This token is used to execute queries against the dbt Cloud API on the user's behalf. User API tokens inherit the permissions of the user that they were created for. These tokens are account-specific; If a user has access to more than one dbt Cloud account with the same email address, you need to create a unique PAT for each one of these accounts. + +:::warning Action required + +The [user API tokens](/docs/dbt-cloud-apis/user-tokens) is being 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. + +The current API key is located under **Personal Settings → API Key.** + +::: + +On Jan X, 2024, all new personal API Access Tokens (PATs) created will be account-specific. PATs differ from [Service Tokens](/docs/dbt-cloud-apis/service-tokens), which remain unaffected by this change. Prior to this update, API keys were user-specific and, as such, were not scoped to an account. To enhance the security of dbt Cloud, we are moving away from this model to account-specific tokens. This has a few implications if you’re using a user token today: + +* **All existing API keys will stop working after April X, 2024:** + * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped personal access tokens. +* **You must create and implement unique tokens in each of your dbt Cloud accounts associated with the same email:** + * For example, paul@atreides.com belongs to two dbt Cloud accounts: Spice Harvesting Account and Guild Navigator Account. Before this release, the same API key was used to access both 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. These API tokens are account-specific and not user-specific. +* **Cross-Account API endpoints will stop working after April X, 2024:** + * These are /v2/accounts and /v3/accounts. Since all tokens are now account-specific, tying all accounts to a username will not work. So /v3/accounts will be deprecated. + * Moving forward, dbt Cloud will no longer support this model. User account metadata will only contain information about the specific account under which the request is 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 API endpoints + +If you’re using any undocumented and unsupported API endpoints, please note that these can be deprecated without any notice. If you're using any undocumented endpoints and have use-cases that are not satisfied by the current API, please reach out to apifeedback@dbt.com. + +::: + +### Migration Checklist + +If you are not using a user API key to access dbt Cloud APIs, you do not need to take any action. If you are using a user API key, please read the following instructions: + +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 **Settings** → **Access Token** + * (Need screenshot) +3. Use this new PAT to replace the old user API key. +4. Ensure that you’re using a PAT only where it’s needed. For any workflows that require a service account, please use a [service token](/docs/dbt-cloud-apis/service-tokens). + + +### Service tokens vs. personal access token (PAT) + +The following use cases highlight scenarios where you should use a 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** — Examples here are Hightouch, Datafold, a custom app you’ve created, etc. All of these integrations should use a service token instead of a PAT. This is because service tokens give you visibility, and you can scope them specifically to only what the integrations need and ensure the least privilege. If you’re using a user API key for these today, we highly recommend that you switch to a service token. +* **Production Terraform** — 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** — 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** — 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. + ## FAQs - + \ No newline at end of file diff --git a/website/sidebars.js b/website/sidebars.js index b1f5ea1fe6f..0566ef8c3a6 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -504,7 +504,6 @@ const sidebarSettings = { link: { type: "doc", id: "docs/dbt-cloud-apis/authentication" }, items: [ "docs/dbt-cloud-apis/authentication", - "docs/dbt-cloud-apis/personal-access-tokens", "docs/dbt-cloud-apis/user-tokens", "docs/dbt-cloud-apis/service-tokens", ], From 4047d5d04dd71eebc72a58250856e37c0d8e373d Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Mon, 5 Feb 2024 15:52:01 -0500 Subject: [PATCH 03/11] Updates based on feedback --- .../docs/dbt-cloud-apis/authentication.md | 13 ++++++++-- .../docs/docs/dbt-cloud-apis/user-tokens.md | 24 ++++--------------- 2 files changed, 16 insertions(+), 21 deletions(-) diff --git a/website/docs/docs/dbt-cloud-apis/authentication.md b/website/docs/docs/dbt-cloud-apis/authentication.md index 7deadd68f18..6028507095e 100644 --- a/website/docs/docs/dbt-cloud-apis/authentication.md +++ b/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,13 @@ pagination_prev: null link="/docs/dbt-cloud-apis/service-tokens" icon="dbt-bit"/> - \ No newline at end of file + + +## 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** — Examples here are Hightouch, Datafold, a custom app you’ve created, etc. All of these integrations should use a service token instead of a PAT. This is because service tokens give you visibility, and you can scope them specifically to only what the integrations need and ensure the least privilege. If you’re using a user API key for these today, we highly recommend that you switch to a service token. +* **Production Terraform** — 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** — 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** — 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. \ No newline at end of file diff --git a/website/docs/docs/dbt-cloud-apis/user-tokens.md b/website/docs/docs/dbt-cloud-apis/user-tokens.md index 429fc1a6a0a..d75f4358e10 100644 --- a/website/docs/docs/dbt-cloud-apis/user-tokens.md +++ b/website/docs/docs/dbt-cloud-apis/user-tokens.md @@ -4,9 +4,11 @@ id: "user-tokens" pagination_next: "docs/dbt-cloud-apis/service-tokens" --- -:::warning +:::warning Action required + +The [user API tokens](/docs/dbt-cloud-apis/user-tokens) is being 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. -Personal API Keys are being deprecated. Please create a new account-scoped API token (under account settings) and use that instead. Learn more about this change and the migration process on the [Personal Access Token](/docs/dbt-cloud-apis/personal-access-tokens) page. +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. @@ -29,15 +31,8 @@ label. Each dbt Cloud user with a [developer license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) can create a personal access token (PAT) to access the dbt Cloud API. This token is used to execute queries against the dbt Cloud API on the user's behalf. User API tokens inherit the permissions of the user that they were created for. These tokens are account-specific; If a user has access to more than one dbt Cloud account with the same email address, you need to create a unique PAT for each one of these accounts. -:::warning Action required - -The [user API tokens](/docs/dbt-cloud-apis/user-tokens) is being 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. - -The current API key is located under **Personal Settings → API Key.** - -::: -On Jan X, 2024, all new personal API Access Tokens (PATs) created will be account-specific. PATs differ from [Service Tokens](/docs/dbt-cloud-apis/service-tokens), which remain unaffected by this change. Prior to this update, API keys were user-specific and, as such, were not scoped to an account. To enhance the security of dbt Cloud, we are moving away from this model to account-specific tokens. This has a few implications if you’re using a user token today: +All new personal API Access Tokens (PATs) created will be account-specific. PATs differ from [Service Tokens](/docs/dbt-cloud-apis/service-tokens), which remain unaffected by this change. Prior to this update, API keys were user-specific and, as such, were not scoped to an account. To enhance the security of dbt Cloud, we are moving away from this model to account-specific tokens. This has a few implications if you’re using a user token today: * **All existing API keys will stop working after April X, 2024:** * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped personal access tokens. @@ -67,15 +62,6 @@ If you are not using a user API key to access dbt Cloud APIs, you do not need to 4. Ensure that you’re using a PAT only where it’s needed. For any workflows that require a service account, please use a [service token](/docs/dbt-cloud-apis/service-tokens). -### Service tokens vs. personal access token (PAT) - -The following use cases highlight scenarios where you should use a 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** — Examples here are Hightouch, Datafold, a custom app you’ve created, etc. All of these integrations should use a service token instead of a PAT. This is because service tokens give you visibility, and you can scope them specifically to only what the integrations need and ensure the least privilege. If you’re using a user API key for these today, we highly recommend that you switch to a service token. -* **Production Terraform** — 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** — 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** — 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. - ## FAQs From 0d8f957936788b61bb3dc6862885e71c94df7a38 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Mon, 5 Feb 2024 16:04:47 -0500 Subject: [PATCH 04/11] Removing dates --- website/docs/docs/dbt-cloud-apis/user-tokens.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/docs/dbt-cloud-apis/user-tokens.md b/website/docs/docs/dbt-cloud-apis/user-tokens.md index d75f4358e10..82c4f17d1ed 100644 --- a/website/docs/docs/dbt-cloud-apis/user-tokens.md +++ b/website/docs/docs/dbt-cloud-apis/user-tokens.md @@ -32,15 +32,15 @@ label. Each dbt Cloud user with a [developer license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) can create a personal access token (PAT) to access the dbt Cloud API. This token is used to execute queries against the dbt Cloud API on the user's behalf. User API tokens inherit the permissions of the user that they were created for. These tokens are account-specific; If a user has access to more than one dbt Cloud account with the same email address, you need to create a unique PAT for each one of these accounts. -All new personal API Access Tokens (PATs) created will be account-specific. PATs differ from [Service Tokens](/docs/dbt-cloud-apis/service-tokens), which remain unaffected by this change. Prior to this update, API keys were user-specific and, as such, were not scoped to an account. To enhance the security of dbt Cloud, we are moving away from this model to account-specific tokens. This has a few implications if you’re using a user token today: +All new personal API Access Tokens (PATs) created will be account-specific. PATs differ from [Service Tokens](/docs/dbt-cloud-apis/service-tokens), which remain unaffected by this change. Prior to this update, 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. This deprecation has a few implications if you’re using a user token today: -* **All existing API keys will stop working after April X, 2024:** +* **All existing API keys will stop working:** * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped personal access tokens. * **You must create and implement unique tokens in each of your dbt Cloud accounts associated with the same email:** * For example, paul@atreides.com belongs to two dbt Cloud accounts: Spice Harvesting Account and Guild Navigator Account. Before this release, the same API key was used to access both 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. These API tokens are account-specific and not user-specific. -* **Cross-Account API endpoints will stop working after April X, 2024:** - * These are /v2/accounts and /v3/accounts. Since all tokens are now account-specific, tying all accounts to a username will not work. So /v3/accounts will be deprecated. +* **Cross-Account API endpoints will stop working:** + * These are /v2/accounts and /v3/accounts. Since all tokens are now account-specific, tying all accounts to a username will not work. * Moving forward, dbt Cloud will no longer support this model. User account metadata will only contain information about the specific account under which the request is made. * Any other accounts that belong to that user account will need to be requested through the PAT that belongs to that account. From 58c8818a9a2a23dcdb52ef0d9e1a0af10922fe07 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Tue, 6 Feb 2024 18:52:59 -0500 Subject: [PATCH 05/11] Updates --- .../docs/dbt-cloud-apis/authentication.md | 12 ++++- .../docs/docs/dbt-cloud-apis/user-tokens.md | 47 +++++++++++-------- website/sidebars.js | 2 +- 3 files changed, 39 insertions(+), 22 deletions(-) diff --git a/website/docs/docs/dbt-cloud-apis/authentication.md b/website/docs/docs/dbt-cloud-apis/authentication.md index 6028507095e..d5e689fcc4c 100644 --- a/website/docs/docs/dbt-cloud-apis/authentication.md +++ b/website/docs/docs/dbt-cloud-apis/authentication.md @@ -21,11 +21,19 @@ pagination_prev: null -## Which token type should you use +## 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** — Examples here are Hightouch, Datafold, a custom app you’ve created, etc. All of these integrations should use a service token instead of a PAT. This is because service tokens give you visibility, and you can scope them specifically to only what the integrations need and ensure the least privilege. If you’re using a user API key for these today, we highly recommend that you switch to a service token. +* **Connecting a partner integration to dbt Cloud** — 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** — 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** — 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** — 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. \ No newline at end of file diff --git a/website/docs/docs/dbt-cloud-apis/user-tokens.md b/website/docs/docs/dbt-cloud-apis/user-tokens.md index 82c4f17d1ed..edb3ffa8d6f 100644 --- a/website/docs/docs/dbt-cloud-apis/user-tokens.md +++ b/website/docs/docs/dbt-cloud-apis/user-tokens.md @@ -29,37 +29,46 @@ label. ## Account-scoped personal access tokens -Each dbt Cloud user with a [developer license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) can create a personal access token (PAT) to access the dbt Cloud API. This token is used to execute queries against the dbt Cloud API on the user's behalf. User API tokens inherit the permissions of the user that they were created for. These tokens are account-specific; If a user has access to more than one dbt Cloud account with the same email address, you need to create a unique PAT for each one of these accounts. +:::info New +On Feb 7, 2024, we introduced a new type of token for individual users called Personal Access Tokens. Note that these are different from [Service Tokens or API Keys](/docs/dbt-cloud-apis/authentication#types-of-api-access-tokens). Prior to 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 as such were not scoped to an account. To enhance the security of dbt Cloud, we are moving away from this model to account-specific tokens. -All new personal API Access Tokens (PATs) created will be account-specific. PATs differ from [Service Tokens](/docs/dbt-cloud-apis/service-tokens), which remain unaffected by this change. Prior to this update, 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. This deprecation has a few implications if you’re using a user token today: +::: + +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 API 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. + +Personal Access Tokens inherit the permissions of the user that created them. For example, if a developer-licensed user with Project Admin role access to certain 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 important if you’ve been using User API keys. Today, the current API key is located under Personal Settings → API Key -* **All existing API keys will stop working:** - * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped personal access tokens. -* **You must create and implement unique tokens in each of your dbt Cloud accounts associated with the same email:** - * For example, paul@atreides.com belongs to two dbt Cloud accounts: Spice Harvesting Account and Guild Navigator Account. Before this release, the same API key was used to access both 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. These API tokens are account-specific and not user-specific. -* **Cross-Account API endpoints will stop working:** - * These are /v2/accounts and /v3/accounts. Since all tokens are now account-specific, tying all accounts to a username will not work. - * Moving forward, dbt Cloud will no longer support this model. User account metadata will only contain information about the specific account under which the request is made. - * Any other accounts that belong to that user account will need to be requested through the PAT that belongs to that account. + This has a few implications if you are using a User API Key today: +* **Personal Access Tokens are more secure** + * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped Personal Access Tokens 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 paul@atreides.com 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 Personal Access Tokens 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 Personal Access Tokens 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 API endpoints +:::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're using any undocumented endpoints and have use-cases that are not satisfied by the current API, please reach out to apifeedback@dbt.com. +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 support@dbt.com ::: -### Migration Checklist +### Using the new Personal Access Tokens -If you are not using a user API key to access dbt Cloud APIs, you do not need to take any action. If you are using a user API key, please read the following instructions: +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 **Settings** → **Access Token** - * (Need screenshot) -3. Use this new PAT to replace the old user API key. -4. Ensure that you’re using a PAT only where it’s needed. For any workflows that require a service account, please use a [service token](/docs/dbt-cloud-apis/service-tokens). +2. Create a new Personal Access Token under Account Settings → API Tokens → Personal Tokens +3. Create and copy the new Personal Access Token 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 ## FAQs diff --git a/website/sidebars.js b/website/sidebars.js index 0566ef8c3a6..d1503a4b204 100644 --- a/website/sidebars.js +++ b/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", From c943f38139c01d9243cf27a7649ebc2311e71414 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Tue, 6 Feb 2024 19:18:21 -0500 Subject: [PATCH 06/11] Updates --- .../docs/docs/dbt-cloud-apis/user-tokens.md | 54 +++++++++---------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/website/docs/docs/dbt-cloud-apis/user-tokens.md b/website/docs/docs/dbt-cloud-apis/user-tokens.md index edb3ffa8d6f..e383cb93c5b 100644 --- a/website/docs/docs/dbt-cloud-apis/user-tokens.md +++ b/website/docs/docs/dbt-cloud-apis/user-tokens.md @@ -4,9 +4,9 @@ id: "user-tokens" pagination_next: "docs/dbt-cloud-apis/service-tokens" --- -:::warning Action required +:::note Action required -The [user API tokens](/docs/dbt-cloud-apis/user-tokens) is being 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. +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.** @@ -14,50 +14,37 @@ Please [contact support](/docs/dbt-support#dbt-cloud-support) with any questions ::: -## 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` -label. - - - - ## 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 are different from [Service Tokens or API Keys](/docs/dbt-cloud-apis/authentication#types-of-api-access-tokens). Prior to 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 as such were not scoped to an account. To enhance the security of dbt Cloud, we are moving away from this model to account-specific tokens. +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 API 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. +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. -Personal Access Tokens inherit the permissions of the user that created them. For example, if a developer-licensed user with Project Admin role access to certain 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. +Personal Access Tokens 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 +### Migrating from user API keys to personal access tokens -This is important if you’ve been using User API keys. Today, the current API key is located under Personal Settings → API Key +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: + This has a few implications if you are using a user API key today: * **Personal Access Tokens are more secure** - * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped Personal Access Tokens away from User API Keys + * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped Personal Access Tokens 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 paul@atreides.com 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 + * For example, if paul@atreides.com 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 Personal Access Tokens 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 Personal Access Tokens 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 + * 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 support@dbt.com +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 [support@dbt.com](mailto:support@dbt.com). ::: @@ -66,10 +53,21 @@ If you’re using any undocumented and unsupported API endpoints, please note th 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 Personal Access Token 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 +2. Create a new Personal Access Token under **Account Settings → API Tokens → Personal Tokens.** +3. Create and copy the new Personal Access Token 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** +label. + + ## FAQs From 0c51ca816de8549c5e3c0f6e58f5dc70f77e66f3 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Tue, 6 Feb 2024 19:21:43 -0500 Subject: [PATCH 07/11] case fix --- .../docs/docs/dbt-cloud-apis/user-tokens.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/website/docs/docs/dbt-cloud-apis/user-tokens.md b/website/docs/docs/dbt-cloud-apis/user-tokens.md index e383cb93c5b..78e09f0250f 100644 --- a/website/docs/docs/dbt-cloud-apis/user-tokens.md +++ b/website/docs/docs/dbt-cloud-apis/user-tokens.md @@ -18,13 +18,13 @@ Please [contact support](/docs/dbt-support#dbt-cloud-support) with any questions :::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. +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. +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. -Personal Access Tokens 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. +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 @@ -32,13 +32,13 @@ This is critical if you’ve been using user API keys. Today, the current API ke This has a few implications if you are using a user API key today: -* **Personal Access Tokens are more secure** - * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped Personal Access Tokens away from user API keys. +* **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 paul@atreides.com 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 Personal Access Tokens 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 Personal Access Tokens 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. + * 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. @@ -48,13 +48,13 @@ If you’re using any undocumented and unsupported API endpoints, please note th ::: -### Using the new Personal Access Tokens +### 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 Personal Access Token to replace the old 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 From 81740f5ac740f59c367ab81e2b249de82529d481 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Tue, 6 Feb 2024 19:22:53 -0500 Subject: [PATCH 08/11] Case fix --- website/docs/docs/dbt-cloud-apis/authentication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/docs/dbt-cloud-apis/authentication.md b/website/docs/docs/dbt-cloud-apis/authentication.md index d5e689fcc4c..8580cf45b40 100644 --- a/website/docs/docs/dbt-cloud-apis/authentication.md +++ b/website/docs/docs/dbt-cloud-apis/authentication.md @@ -23,11 +23,11 @@ pagination_prev: null ## 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. +**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. +**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. +**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 From 1882da3115fc7c83d802a7330c0f301cfab56746 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Wed, 7 Feb 2024 12:50:30 -0500 Subject: [PATCH 09/11] More edits --- .../docs/docs/dbt-cloud-apis/authentication.md | 6 +++--- website/docs/docs/dbt-cloud-apis/user-tokens.md | 16 ++++++++-------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/website/docs/docs/dbt-cloud-apis/authentication.md b/website/docs/docs/dbt-cloud-apis/authentication.md index 8580cf45b40..8f864a843d7 100644 --- a/website/docs/docs/dbt-cloud-apis/authentication.md +++ b/website/docs/docs/dbt-cloud-apis/authentication.md @@ -23,7 +23,7 @@ pagination_prev: null ## 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. +**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. @@ -33,7 +33,7 @@ pagination_prev: null 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** — 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. +* **Connecting a partner integration to dbt Cloud** — Some examples include Hightouch, Datafold, a custom app you’ve created, etc. These types of integrations should use a service token instead of a PAT because service tokens give you visibility, and you can scope them to only what the integration needs and ensure the least privilege. We highly recommend switching to a service token if you’re using a user API key for these integrations today. * **Production Terraform** — 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** — 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** — 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. \ No newline at end of file +* **Testing a custom script and staging Terraform or Postman** — We recommend using a PAT as this is a developmental workflow and is scoped to the user making the changes. When you push this script or Terraform into production, use a service token instead. \ No newline at end of file diff --git a/website/docs/docs/dbt-cloud-apis/user-tokens.md b/website/docs/docs/dbt-cloud-apis/user-tokens.md index 78e09f0250f..824ec9a86b1 100644 --- a/website/docs/docs/dbt-cloud-apis/user-tokens.md +++ b/website/docs/docs/dbt-cloud-apis/user-tokens.md @@ -26,19 +26,19 @@ Each dbt Cloud user with a [Developer license](https://docs.getdbt.com/docs/clo 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 +### Migrate 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** +The migration to PATs is critical if you are 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: + There are a few things to understand 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.** +* Personal access tokens are more secure. + * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped Personal Access Tokens. +* You must create and use unique tokens in each one of your dbt Cloud accounts that share the same email address. * For example, if paul@atreides.com 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. +* 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 associated 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. From 8ce64cbffd1b2697acca7680736ff4cf055ef283 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Wed, 7 Feb 2024 12:54:13 -0500 Subject: [PATCH 10/11] Fixing case --- website/docs/docs/dbt-cloud-apis/user-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/dbt-cloud-apis/user-tokens.md b/website/docs/docs/dbt-cloud-apis/user-tokens.md index 824ec9a86b1..7fbcabfdd71 100644 --- a/website/docs/docs/dbt-cloud-apis/user-tokens.md +++ b/website/docs/docs/dbt-cloud-apis/user-tokens.md @@ -33,7 +33,7 @@ The migration to PATs is critical if you are using user API keys today. The curr There are a few things to understand if you are using a user API key today: * Personal access tokens are more secure. - * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped Personal Access Tokens. + * To promote least privilege and high security assurance for your dbt Cloud accounts, we highly recommend moving to the new account-scoped personal access tokens. * You must create and use unique tokens in each one of your dbt Cloud accounts that share the same email address. * For example, if paul@atreides.com 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. From 306ab82f9c40c989bb72d8d8fb3028b125f85819 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Wed, 7 Feb 2024 15:51:02 -0500 Subject: [PATCH 11/11] Update website/docs/docs/dbt-cloud-apis/authentication.md Co-authored-by: Leona B. Campbell <3880403+runleonarun@users.noreply.github.com> --- website/docs/docs/dbt-cloud-apis/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/dbt-cloud-apis/authentication.md b/website/docs/docs/dbt-cloud-apis/authentication.md index 8f864a843d7..4d7c4d4c06a 100644 --- a/website/docs/docs/dbt-cloud-apis/authentication.md +++ b/website/docs/docs/dbt-cloud-apis/authentication.md @@ -31,7 +31,7 @@ pagination_prev: null ### 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. +You should use service tokens broadly for any production workflow where you need a service account. You should use PATs only for developmental workflows _or_ dbt Cloud client workflows that require user context. The following examples show you when to use a personal access token (PAT) or a service token: * **Connecting a partner integration to dbt Cloud** — Some examples include Hightouch, Datafold, a custom app you’ve created, etc. These types of integrations should use a service token instead of a PAT because service tokens give you visibility, and you can scope them to only what the integration needs and ensure the least privilege. We highly recommend switching to a service token if you’re using a user API key for these integrations today. * **Production Terraform** — Use a service token since this is a production workflow and is acting as a service account and not a user account.