Service account tokens
If you have service tokens created on or before July 18, 2023, please read this important update.
Service account tokens enable you to securely authenticate with the dbt Cloud API by assigning each token a narrow set of permissions that more precisely manages access to the API. While similar to User API tokens, service account tokens belong to an account rather than a user.
You can use service account tokens for system-level integrations that do not run on behalf of any one user. Assign any permission sets available in dbt Cloud to your service account token, which can vary slightly depending on your plan:
- Enterprise plans can apply any permission sets available to service tokens.
- Team plans can apply Account Admin, Member, Job Admin, Read-Only, and Metadata permissions set to service tokens.
You can assign as many permission sets as needed to one token. For more on permissions sets, see "Enterprise Permissions."
Generate service account tokens
You can generate service tokens if you have a Developer license and account admin permissions. To create a service token in dbt Cloud, follow these steps:
- Open the Account Settings page by clicking the gear icon on the right-hand side.
- On the left sidebar, click on Service Tokens.
- Click the + New Token button to generate a new token.
- Once the token is generated, you won't be able to view this token again so make sure to save it somewhere safe.
Permissions for service account tokens
You can assign service account tokens to any permission set available in dbt Cloud. When you assign a permission set to a token, you will also be able to choose whether to grant those permissions to all projects in the account or to specific projects.
Team plans using service account tokens
The following permissions can be assigned to a service account token on a Team plan.
Account Admin
Account Admin service tokens have full read + write access to an account, so please use them with caution. A Team plan refers to this permission set as an "Owner role." For more on these permissions, see Account Admin.
Metadata Only
Metadata-only service tokens authorize requests to the Discovery API.
Semantic Layer Only
Semantic Layer-only service tokens authorize requests to the Semantic Layer APIs.
Job Admin
Job admin service tokens can authorize requests for viewing, editing, and creating environments, triggering runs, and viewing historical runs.
Member
Member service tokens can authorize requests for viewing and editing resources, triggering runs, and inviting members to the account. Tokens assigned the Member permission set will have the same permissions as a Member user. For more information about Member users, see "Self-service permissions".
Read-only
Read-only service tokens can authorize requests for viewing a read-only dashboard, viewing generated documentation, and viewing source freshness reports.
Enterprise plans using service account tokens
The following permissions can be assigned to a service account token on an Enterprise plan. For more details about these permissions, see "Enterprise permissions."
Account Admin
Account Admin service tokens have full read + write access to an account, so please use them with caution. For more on these permissions, see Account Admin.
Security Admin
Security Admin service tokens have certain account-level permissions. For more on these permissions, see Security Admin.
Billing Admin
Billing Admin service tokens have certain account-level permissions. For more on these permissions, see Billing Admin.
Metadata Only
Metadata-only service tokens authorize requests to the Discovery API.
Semantic Layer Only
Semantic Layer-only service tokens authorize requests to the Semantic Layer APIs.
Job Admin
Job Admin service tokens can authorize requests for viewing, editing, and creating environments, triggering runs, and viewing historical runs. For more on these permissions, see Job Admin.
Account Viewer
Account Viewer service tokens have read-only access to dbt Cloud accounts. For more on these permissions, see Account Viewer on the Enterprise Permissions page.
Admin
Admin service tokens have unrestricted access to projects in dbt Cloud accounts. You have the option to grant that permission all projects in the account or grant the permission only on specific projects. For more on these permissions, see Admin Service on the Enterprise Permissions page.
Git Admin
Git admin service tokens have all the permissions listed in Git admin on the Enterprise Permissions page.
Database Admin
Database admin service tokens have all the permissions listed in Database admin on the Enterprise Permissions page.
Team Admin
Team admin service tokens have all the permissions listed in Team admin on the Enterprise Permissions page.
Job Viewer
Job viewer admin service tokens have all the permissions listed in Job viewer on the Enterprise Permissions page.
Developer
Developer service tokens have all the permissions listed in Developer on the Enterprise Permissions page.
Analyst
Analyst admin service tokens have all the permissions listed in Analyst on the Enterprise Permissions page.
Stakeholder
Stakeholder service tokens have all the permissions listed in Stakeholder on the Enterprise Permissions page.
Service token update
On July 18, 2023, dbt Labs made critical infrastructure changes to service account tokens. These enhancements improve the security and performance of all tokens created after July 18, 2023. To ensure security best practices are in place, we recommend you rotate your service tokens created before this date.
To rotate your token:
- Navigate to Account settings and click Service tokens on the left side pane.
- Verify the Created date for the token is on or before July 18, 2023.
Service token created date - Click + New Token on the top right side of the screen. Ensure the new token has the same permissions as the old one.
- Copy the new token and replace the old one in your systems. Store it in a safe place, as it will not be available again once the creation screen is closed.
- Delete the old token in dbt Cloud by clicking the trash can icon. Only take this action after the new token is in place to avoid service disruptions.