User tokens teamenterprise

Announcement

User tokens will be deprecated on October 22nd, 2024.

The user API tokens are being replaced by account-scoped personal access tokens(PATs). If you do not rotate your existing user tokens with PATs by October 22nd, the services using the tokens will encounter errors.

Cloud CLI config files need to be re-downloaded before October 22nd, 2024.

The current API key is located under Personal Settings → API Key.

Please contact support with any questions or concerns.

Account-scoped personal access tokens

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. 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 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 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.

Migrate from user API keys to personal access tokens

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.

There are a few things to understand if you are using a user API key today:

• Personal access tokens are more secure.
  • To promote the 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@example.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 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 associated with 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.

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@getdbt.com.

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 it's 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 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 that they were created for.

You can find your user API token in the Profile page under the API Access label.

Finding your API token in your dbt Cloud Profile

FAQs

How can I rotate my user API token?

For security reasons and best practices, you should aim to rotate API keys every so often. You can rotate your API key automatically with the push of a button in your dbt Cloud environment or manually using the command line.

Automatic

To automatically rotate your API key:

1. Navigate to the Account settings by clicking the gear icon in the top right of your dbt Cloud account.
2. Select API Access from the lefthand side.
3. In the API pane, click Rotate.

Click the rotate button to generate a new key

Manual

1. Rotate your User API token by replacing YOUR_USER_ID, YOUR_CURRENT_PAT_TOKEN, and YOUR_ACCESS_URL with your information in the following request.

curl --location --request POST 'https://cloud.getdbt.com/api/v3/accounts/YOUR_ACCOUNT_ID/users/YOUR_USER_ID/apikey/' \
--header 'Authorization: Token YOUR_CURRENT_PAT_TOKEN'

• Find your YOUR_USER_ID by reading How to find your user ID.
• Find your YOUR_CURRENT_TOKEN by going to Profile Settings -> API Access and copying the API key.
• Find YOUR_ACCESS_URL for your region and plan.

If YOUR_USER_ID = 123, YOUR_CURRENT_TOKEN = abcf9g, then your curl request will be:

curl --location --request POST 'https://YOUR_ACCESS_URL/api/v2/users/123/apikey/' \

--header 'Authorization: Token abcf9g'

2. Find the new key in the API response or in dbt Cloud.

3. To find the new key in dbt Cloud, go to Profile Settings -> API Access.

dbt Cloud deployments

If your dbt Cloud deployment uses a different access URL, replace YOUR_ACCESS_URL with the URL of your instance.

For example, if your deployment is Virtual Private dbt:

✅ http://cloud.customizedurl.getdbt.com/
❌ http://cloud.getdbt.com/

Where can I find my user id?

Knowing your dbt Cloud user ID can help with actions related to rotating your API token, interacting with support, and more.

To find your user ID in dbt Cloud, read the following steps:

1. Go to Account Settings, Team, and then Users,
2. Select your user,
   
3. In the address bar, the number after /users is your user ID.
4. Copy that number or save it somewhere safe.
   

For example, if the URL is https://YOUR_ACCESS_URL/settings/accounts/12345/users/67891 — the user ID is 67891