What you will be able to do
- Choose between a service token and a personal access token for a given API workflow
- Create a service token in Account settings and store it correctly
- Scope a service token with the permission sets and projects an integration needs
- Rotate a service token without downtime and diagnose a 403 caused by IP restrictions
Key concept
Service account token — An API credential that belongs to the dbt account rather than to any person. It carries only the permission sets you assign it, so an integration gets exactly the access it needs and keeps working when people leave.
1.Service tokens versus personal access tokens
Every request to the dbt APIs is authorised with a token, and dbt supports two kinds: personal access tokens (PATs) and service account tokens. The Administrative API, the Discovery API and the Semantic Layer APIs all accept them. Choosing the wrong kind doesn't cause an error on day one. It shows up later, when the integration breaks or turns out to have too much access.
A PAT acts as the person who created it. PATs inherit the permissions of the user that created them, so a token made by a Project Admin gets Project Admin on the same projects. A service token belongs to the account and has no user behind it. It holds only the permission sets you assign to it, which makes it the right credential for system-level integrations that don't run on behalf of any one person.
The rule of thumb is production versus development. Use a service token for any production workflow that needs a service account. Use a PAT for developmental work, and for clients that need a user context. The dbt platform CLI is the clearest example: it works within the context of a user, so it takes a PAT. Endpoints that create or update user credentials also require a PAT.
| Workflow | Token | Reason |
|---|---|---|
| Partner integration (Hightouch, Datafold, Semantic Layer Google Sheets, a custom app) | Service token | Gives visibility and can be scoped to least privilege |
| Production Terraform | Service token | Acts as a service account, not a user account |
| Testing a custom script, staging Terraform or Postman | PAT | Developmental workflow scoped to the user making changes |
| dbt platform CLI | PAT | Works within the context of a user |
| Endpoints that create and update user credentials | PAT | The endpoint requires user context |
A script often starts on a PAT while someone tests it. When it moves to production, switch it to a service token. If a partner integration is running on someone's PAT today, the recommendation is to move it to a service token. A service token can be scoped to what the integration needs, and it doesn't stop working when its owner's access changes.
Checkpoint 1 of 8· Check yourself
A team has tested a Terraform configuration in staging with an engineer's personal access token. It is now being promoted to manage the production dbt account. What should it authenticate with?
Production Terraform acts as a service account, not as a user, so it should use a service token. A PAT is only appropriate during the staging and testing phase.
“Use a service token since this is a production workflow and is acting as a service account and not a user account.”Source: docs.getdbt.com
Checkpoint 2 of 8· Exam question
A platform admin on an Enterprise dbt Cloud account needs a token so a nightly Airflow instance can trigger dbt Cloud jobs via the API without acting as any individual employee. How should the admin issue this credential?
Correct answer: B — Go to Account settings, open Service Tokens, click Create service token, and assign a Job Admin permission scoped to the relevant project, since creating it requires Account Admin permissions.
- A. Service tokens are account-level credentials with their own assignable permissions; they do not inherit the license of whoever created them, and Member is not a job-triggering permission anyway.
- B. This is correct: service tokens are created under Account settings > Service Tokens, and issuing one requires Account Admin permissions, after which a scoped Job Admin permission lets the orchestration tool trigger runs on just the intended project.
- C. Service tokens are not created from an Environment settings page, and picking a license tier there is not part of the token-creation flow; license type governs users, not the token's own permission scope.
- D. A personal access token still authenticates as the creating individual user, which defeats the goal of a system-level credential that keeps working independent of any one employee's account.
2.Creating a service token in Account settings
Creating a service token takes two things together: a Developer license and account admin permissions. A user who has one without the other can't create tokens. Inside the Semantic Layer setup, a user without token permissions sees a prompt to contact their admin instead of the token option.
The token is created in a short sequence in the dbt UI:
1. Click your account name in the left side menu and select Account settings. 2. On the left sidebar, click Service Tokens. 3. Click + Create service token and enter a name for the token. 4. Add the permissions the integration needs. 5. Copy the generated token and store it somewhere safe.
The last step can't be skipped. dbt shows the token value only once, at creation. If nobody copies it before closing the screen, it can't be recovered, and you'll have to generate a new token. Paste it directly into the integration's secret store, not into a chat message or ticket.
Creating tokens through the API has a restriction of its own. A PAT can't create a service token, and that request fails with a 400 error. To create tokens programmatically, authenticate with an existing service token. A bootstrap token made in the UI can then issue the narrower tokens for each integration.
Checkpoint 3 of 8· Put it in order
Put the steps for creating a service token in order
- 1.Add the necessary permissions
- 2.Save the generated token somewhere safe before leaving the screen
- 3.Click Service Tokens on the left sidebar
- 4.Click your account name in the left side menu and select Account settings
- 5.Click + Create service token and enter a name
Service tokens live under Account settings → Service Tokens. You name the token, assign its permissions, and then save the value, because it is shown only once.
“Click the + Create service token button to generate a new token. Enter a name for your token. Add the necessary permissions.”Source: docs.getdbt.com
Checkpoint 4 of 8· Exam question
An Enterprise account has IP restrictions enabled with an allowlist containing only the company VPN egress addresses and the git provider's published ranges. A CI runner hosted on a third-party build service calls the dbt Cloud API with a valid, correctly scoped service token, but every request returns 403 Forbidden. What is the most likely cause and fix?
Correct answer: A — The IP allowlist blocks any address not explicitly listed, so the CI runner's outbound IP range must be added to the allowlist before its requests will succeed.
- A. This is correct: an allowlist-model IP restriction blocks all traffic, including service tokens, from addresses not on the list, so the fix is adding the CI runner's egress range.
- B. Service tokens do not have a built-in expiration tied to originating IP address, so this explanation does not match how dbt Cloud enforces token validity.
- C. IP restrictions apply to service tokens and personal API tokens as well as UI access, so this option describes a scope entirely outside what IP restrictions actually govern.
- D. dbt Cloud's API authenticates with a bearer token regardless of whether it is a personal or service token; switching to Basic auth with a username and password is not a supported authentication method.
3.Scoping a token with permission sets and projects
A service token's access comes entirely from the permission sets attached to it. Unlike a PAT, it inherits nothing. You can assign as many sets as a token needs, and for each one you choose whether it applies to all projects in the account or only to specific projects. A token for one team's Discovery API dashboard should be limited to that team's project, not the whole account. The sets themselves are covered under [permission sets](lesson:5.2). Here, the question is which of them a token may carry.
Your plan decides which permission sets you can assign to a token. On Enterprise and Enterprise+, any available permission set can go on a service token. Developer and Starter plans can only assign Semantic Layer permissions. Legacy Team plans can assign Account Admin, Member, Job Admin, Read-Only, Metadata and Semantic Layer.
| Plan | Assignable to service tokens |
|---|---|
| Enterprise and Enterprise+ | Any permission set available to service tokens |
| Developer and Starter | Semantic Layer permissions |
| Legacy Team | Account Admin, Member, Job Admin, Read-Only, Metadata, Semantic Layer |
"Any permission set" has at least one exception. v2 Migration Admin can be assigned only to user accounts and never to a service token. If an automated process has to perform dbt v2 upgrades while the upgrade restriction is on, give it Account Admin, which works on both users and tokens.
Least privilege comes down to matching the set to the job:
- A Discovery API integration needs Metadata Only, a read-only set covering models, runs, sources and tests. - A BI tool querying the Semantic Layer needs Semantic Layer Only plus Metadata Only. When you map a token during Semantic Layer setup, dbt selects these two for you. - Account Admin gives a token full read and write access to the account. Reserve it for automation that really administers the account, such as production Terraform.
Checkpoint 5 of 8· Match them up
Match each integration to the permission set its service token should carry
Tap a term, then the definition that fits it.
Metadata is the read-only Discovery API set. Semantic Layer tokens get both Semantic Layer Only and Metadata Only. Account Admin is the full-access set, and it is the only upgrade-capable set that service tokens accept.
“Name the token, set permissions to 'Semantic Layer Only' and 'Metadata Only', and click Save.”Source: docs.getdbt.com
4.Rotating tokens and fixing 403 errors
Rotating a token means replacing it without a gap in service. dbt changed how tokens are generated and validated on July 18, 2023, and only tokens created after that date benefit from the faster validation. Older tokens still work. If one is used for high-frequency API calls, though, rotating it reduces latency.
The order matters because the old token has to keep working until its replacement is live:
1. In Account settings → Service tokens, check that the token's Created date is on or before July 18, 2023. 2. Click + New Token and give it the same permissions as the old one. 3. Copy the new token and replace the old one in every system that uses it. 4. Delete the old token with the trash can icon, and only after step 3 is done.
Checkpoint 6 of 8· Check yourself
An integration polls the Administrative API every few seconds using a service token created in March 2023. Which rotation plan is correct?
Older tokens remain valid, but a high-frequency caller benefits from rotation. Deleting the old token before the new one is in place causes an outage.
“Only take this action after the new token is in place to avoid service disruptions.”Source: docs.getdbt.com
A service token with the right permissions can still be blocked at the network layer. All service token traffic goes through the account's IP restrictions. A request from an address that isn't on the allowlist gets a 403 with account_access_denied set to true, however powerful the token is. The fix is to add the integration's CIDRs to the allowlist (see [IP allowlisting](lesson:1.2)), not to add permission sets. The is_service_token field in the response confirms which kind of credential was rejected.
{
"status": {
"code": 403,
"is_success": False,
"user_message": ("Forbidden: Access denied"),
"developer_message": None,
},
"data": {
"account_id": <account_id>,
"user_id": <user_id>,
"is_service_token": <boolean describing if it's a service token request>,
"account_access_denied": True,
},
}Checkpoint 7 of 8· Check yourself
Which change resolves a service token's 403 response that has account_access_denied set to True?
This 403 means the calling IP isn't allowlisted. Allowlisting the integration's network addresses fixes it. Changing permissions or token type doesn't.
“To resolve this, you should add your third-party integration CIDRs (network addresses) to your allowlist.”Source: docs.getdbt.com
Checkpoint 8 of 8· Exam question
A security-conscious admin is issuing a service token for a CI pipeline that only needs to trigger dbt Cloud jobs and poll their run status, and must never edit warehouse connections, invite users, or touch billing. Select the choices that describe an appropriate way to scope this token.(Select 2)
Correct answers: B, C — Assign the Job Admin permission scoped only to the specific project the CI pipeline builds, rather than granting it across every project in the account.; Scope the token to Job Admin or Job Runner rather than Account Admin, since those roles can trigger and monitor runs without connection, billing, or user-management access.
- A. Account Admin is an account-wide permission set that includes billing, connections, and user management regardless of project scoping, so restricting the project does not narrow those capabilities away.
- B. This is correct: narrowing the permission to the single relevant project, rather than all projects in the account, limits the token's reach to exactly the pipeline it serves.
- C. This is correct: Job Admin and Job Runner are built specifically for triggering and monitoring runs and exclude connection editing, billing, and user administration by design.
- D. Billing Admin grants access to billing and invoicing settings, which is unrelated to viewing job run metrics and would give the pipeline far more access than it needs.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Any authenticated API caller, including a personal access token, can create new service tokens through the API.Why is that wrong?
A request to create a service token that is authenticated with a PAT fails with a 400 error. New tokens must be created from an existing service token, or in the UI.
Covered in Creating a service token in Account settings
2.An admin can come back to Account settings later to copy a service token's value.Why is that wrong?
The value is shown only at creation. If it isn't saved then, the token has to be replaced with a new one.
Covered in Creating a service token in Account settings
3.On Enterprise, every permission set, including v2 Migration Admin, can be assigned to a service token.Why is that wrong?
v2 Migration Admin is for user accounts only. A token that needs to perform upgrades must use Account Admin.
Covered in Scoping a token with permission sets and projects
4.Developer and Starter plans can give a service token the same permission sets as Enterprise.Why is that wrong?
On Developer and Starter plans, only Semantic Layer permissions can be assigned to service tokens.
Covered in Scoping a token with permission sets and projects
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://docs.getdbt.com/docs/dbt-apis/authenticationOfficial docs
“Use a service token since this is a production workflow and is acting as a service account and not a user account.”
↩︎ Service tokens versus personal access tokens“Use PATs to authenticate to any API endpoint that requires user context”
↩︎ Service tokens versus personal access tokens - 2.https://docs.getdbt.com/docs/dbt-apis/user-tokensOfficial docs
“PATs inherit the permissions of the user that created them.”
↩︎ Service tokens versus personal access tokens“use an existing service token to create new ones instead”
↩︎ Creating a service token in Account settings“Requests to create a service token authenticated with a PAT return a 400 error”
↩︎ Exam trap 1 - 3.https://docs.getdbt.com/docs/dbt-apis/service-tokensOfficial docs
“You can use service account tokens for system-level integrations that do not run on behalf of any one user.”
↩︎ Service tokens versus personal access tokens“You can generate service tokens if you have a Developer license and account admin permissions.”
↩︎ Creating a service token in Account settings“you will also be able to choose whether to grant those permissions to all projects in the account or to specific projects.”
↩︎ Scoping a token with permission sets and projects“Enterprise and Enterprise+ plans can apply any permission sets available to service tokens.”
↩︎ Scoping a token with permission sets and projects“Old tokens remain valid, but if they are used in high-frequency API invocations, we recommend you rotate them for reduced latency.”
↩︎ Rotating tokens and fixing 403 errors“While similar to personal access tokens, service account tokens belong to an account rather than a user.”
↩︎ Key concept“Once the token is generated, you won't be able to view this token again so make sure to save it somewhere safe.”
↩︎ Exam trap 2“Developer and Starter plans can apply Semantic Layer permissions set to service tokens.”
↩︎ Exam trap 4“Click the + Create service token button to generate a new token. Enter a name for your token. Add the necessary permissions.”
↩︎ Checkpoint“Only take this action after the new token is in place to avoid service disruptions.”
↩︎ Checkpoint - 4.https://docs.getdbt.com/docs/dbt-apis/overviewOfficial docs
“dbt supports two types of API Tokens: personal access tokens and service account tokens.”
↩︎ Service tokens versus personal access tokens - 5.
“Metadata is intended to be a read-only Discovery API integration permission set.”
↩︎ Scoping a token with permission sets and projects“v2 Migration Admin — Assign to user accounts only. Cannot be assigned to service tokens.”
↩︎ Exam trap 3 - 6.
“any service tokens mapped to that credential in the project will no longer work and will break for any end users.”
↩︎ Scoping a token with permission sets and projects“Name the token, set permissions to 'Semantic Layer Only' and 'Metadata Only', and click Save.”
↩︎ Checkpoint - 7.
“All service token traffic is subject to IP restrictions.”
↩︎ Rotating tokens and fixing 403 errors“To resolve this, you should add your third-party integration CIDRs (network addresses) to your allowlist.”
↩︎ Checkpoint