What you will be able to do
- Locate where a Snowflake key pair credential lives in dbt for development and deployment environments
- Generate a replacement key in a format dbt v2 accepts and register its public half on the Snowflake user
- Choose the right API token to update credentials programmatically
- Rotate a credential or token in the create-swap-delete order without breaking running jobs
- Diagnose the errors that appear when a rotated key is pasted or registered incorrectly
Key concept
Overlap rotation — Rotating a secret means bringing the replacement into service before the old one is retired. You create the new key or token with the same access, swap it into every system that uses it, and delete the old one only after that.
1.What a key pair credential is and where it lives
On dbt platform, a key pair is the credential you will most often rotate, because it is the default for Snowflake. You can no longer create Snowflake credentials with a username and password. New development and deployment credentials default to key pair authentication. Snowflake OAuth is also available for user credentials on Enterprise-tier plans when it is configured on the connection. A key pair has two halves. The public key is attached to the Snowflake user. The private key, plus an optional passphrase, is stored in dbt. Rotating the pair means replacing both halves, and the private half sits in a different place depending on the environment type.
Deployment credentials for Production, Staging and General environments are shared and are set up centrally in the Connections area of Account settings. Development credentials belong to individual people, and each user stores theirs in the Credentials area of their own profile. dbt also wraps each deployment environment's connection, credentials and extended attributes in a project-level profile. You can manage profiles through the API, but they don't apply to development environments, where every user's credentials are their own. The [split between development and deployment access](lesson:3.1) therefore decides whose key you are rotating and where the new private key goes.
| Credential | Configured in | Owned by |
|---|---|---|
| Deployment (Production, Staging, General) | Connections area of Account settings | The account, shared by jobs |
| Development | Credentials area of the user profile | The individual user |
Checkpoint 1 of 8· Check yourself
A security team asks you to rotate the key that the nightly Production jobs use to connect to Snowflake. Where does the new private key go?
Production is a deployment environment, and deployment credentials are configured centrally under Connections in Account settings. User profiles hold development credentials only.
“Configure deployment environment (Production, Staging, General) credentials globally in the Connections area of Account settings.”Source: docs.getdbt.com
2.Generating the new key and registering its public half
Start with the key format, because a key that dbt v2 can't read fails even when every other step is right. Here dbt v2 means the dbt v2 Snowflake adapter, which applies both to the dbt platform Snowflake connection marked "dbt v2 compatible" and to a local profiles.yml; it is unrelated to the Administrative API's v2 routes. dbt recommends PKCS#8 with AES-256 encryption. Legacy 3DES encryption and headerless key formats are not supported. If dbt reports Key is PKCS#1 (RSA private key). Snowflake requires PKCS#8, the fix is to re-export the key, not to keep retrying the connection.
openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 aes-256-cbc -inform PEM -out rsa_key.p8Next, attach the public half to the Snowflake user that dbt connects as, with an alter user statement. Snowflake checks dbt's signature against this key, so until it is set, the new private key will not authenticate. For development credentials that user is the developer's own; for deployment credentials it is the Snowflake user or service account the connection uses.
Checkpoint 2 of 8· Fill the gap
Which property completes the statement that registers the new public key on the Snowflake user?
alter user jsmith set ? ='MIIBIjANBgkqh...';Snowflake stores only the public half, in rsa_public_key. The private key and passphrase are stored in dbt's credential, not on the Snowflake user.
Source: docs.getdbt.comFinally, dbt needs the private half. Put it in the Private Key field, and in the Private Key Passphrase field if the key is encrypted. Unencrypted keys are allowed, so add a passphrase only if you need one. The key is entered as a string, either Base64-encoded DER or plain-text PEM, and the PEM form must keep its -----BEGIN ENCRYPTED PRIVATE KEY----- and -----END ENCRYPTED PRIVATE KEY----- lines. Rotation can't be shortcut through an environment variable: the private key field does not support an env_var() reference. The new key has to be written into the credential itself. That is why rotating a key ends with updating a dbt credential, by hand or through the API.
Sources1
3.Choosing the token that updates credentials through the API
Doing the swap through the dbt Administrative API turns rotation into a repeatable script rather than a list of manual clicks. The API manages the account as well as running jobs. dbt recommends v3 in general, though some routes still exist only in v2, and many endpoints can also be called through the dbt Terraform provider.
What decides whether the call succeeds is the token that authenticates it. Endpoints that create and update user credentials, which means a developer's own credentials, need user context, and only a personal access token (PAT) carries it. A [service account token](lesson:3.2) belongs to the account rather than to a person, so it fits system-level integrations that do not act on behalf of any one user, such as an orchestrator that triggers jobs. Production automation that acts as a service account, Terraform included, uses a service token, while PATs suit developmental workflows. A script that writes a new private key into a developer's credential therefore runs with a PAT.
Checkpoint 3 of 8· Check yourself
An automation script calls the API endpoint that updates a user's Snowflake credential to install a newly rotated private key. Which token should authenticate it?
Endpoints that create or update user credentials require user context, and PATs provide it. Service account tokens belong to the account and are not tied to any one user.
“Use PATs to authenticate to any API endpoint that requires user context (for example, endpoints to create and update user credentials).”Source: docs.getdbt.com
Checkpoint 4 of 8· Exam question
A platform team maintains a service token used by an in-house orchestration tool to trigger production dbt Cloud jobs through the Administrative API. Compliance now requires the token to be rotated on a fixed schedule. Which sequence describes the correct way to rotate this token without interrupting the orchestration tool's job runs?
Correct answer: A — Create a new service token with the same permission set, update the orchestration tool's stored credential, confirm a successful job trigger, then delete the old token.
- A. Creating the replacement first keeps a valid credential available at every point in the process, and confirming a successful trigger before deleting the old token guarantees the swap worked before removing the fallback.
- B. Deleting the existing token before the replacement is in place leaves the orchestration tool unauthenticated for the gap between deletion and the update, which is exactly the outage rotation is meant to avoid.
- C. A service token's value cannot be edited in place; renaming or changing permissions does not regenerate the underlying secret, so this does not accomplish a rotation at all.
- D. Service tokens are account-level credentials, not tied to a suspendable user account, and dbt Cloud does not automatically issue replacement tokens on any schedule.
4.Rotating in order: create, swap, then delete
Every rotation follows the same order, whatever the secret. Create the replacement with the same access, put it into every system that uses it, and only then remove the old one. If you delete first, every job, integration or script still holding the old secret fails until the new one arrives. If you create the new one with fewer permissions, the swap looks successful until the first call that needed the permission you dropped.
API tokens are secrets too, and they follow this order. For a PAT, dbt's guidance is to rotate regularly by creating a new token and deleting the old one once the new one is in place. Service tokens have their own procedure, in Account settings under Service tokens. The rotation steps name the button + New Token, while the page for creating a service token calls it + Create service token. A service token is shown only once, at creation, so copy it into the consuming system before you close that screen.
A swapped token can still fail for a reason unrelated to the swap. All service token traffic is subject to IP restrictions, so a request from an address that is not on the allowlist comes back as a 403 with the message Forbidden: Access denied. The fix is to add the integration's CIDRs (network addresses) to the allowlist, not to rotate the token again.
Checkpoint 5 of 8· Put it in order
Put the steps for rotating a service token in order
- 1.Copy the new token and replace the old one in your systems
- 2.Delete the old token with the trash can icon
- 3.Open Account settings and select Service tokens
- 4.Click + New Token and give it the same permissions as the old token
The new token has to exist, with the same permissions, and be in use before the old one is deleted. Otherwise integrations still using the old token break.
“Only take this action after the new token is in place to avoid service disruptions.”Source: docs.getdbt.com
Checkpoint 6 of 8· Exam question
Your dbt Cloud account has IP restrictions enabled with an allowlist that includes only the CIDR ranges of your CI runners. After rotating a service token used by a third-party BI tool that calls the Administrative API from a different network range, the BI tool's calls start failing with a 403 'Forbidden: Access denied' response. What is the most likely cause?
Correct answer: A — The new token's requests originate from an IP range that is not in the account's allowlist, so the platform rejects them regardless of the token's validity.
- A. IP allowlist restrictions apply to every request regardless of which valid token is presented, so traffic from the BI tool's network range is rejected with a 403 exactly as described, independent of the rotation itself.
- B. Nothing in the scenario indicates the new token was assigned fewer permissions than the old one, and a permission mismatch would typically surface as a different authorization error rather than this pattern.
- C. An unrecognized or deleted credential produces an authentication failure rather than the access-denied response described, and the scenario specifies the tool is already using the newly rotated token.
- D. Service token permissions can be scoped to specific projects, but the scenario gives no indication of a project mismatch, and that misconfiguration would not typically manifest as this network-level denial.
5.Errors that follow a bad swap
Key errors after a rotation trace back to how the key was pasted or registered. Could not deserialize key data usually means the private key was damaged on the way into dbt: part of it wasn't copied, dashes are missing, or the commented BEGIN and END lines were dropped. Paste the key into a text editor and check it before putting it into dbt.
A JWT token is invalid error has two possible causes. When dbt connects, it gets a JWT that is valid for only 60 seconds, so a slow response from Snowflake can cause a transient failure that a retry fixes. The other cause is that the public key was not entered correctly on the Snowflake user, so check the rsa_public_key you registered as well as the connection.
Checkpoint 7 of 8· Match them up
Match each error after a key rotation to its likely cause
Tap a term, then the definition that fits it.
Each error points to a different step. Deserialization errors come from pasting the private key into dbt, JWT errors from the public key or connection timing, and PKCS#1 errors from the key format.
“This could be because of mistakes like not copying correctly, missing dashes, or leaving out commented lines.”Source: docs.getdbt.com
Token errors on the API side differ from key errors, and the token type matters. A PAT inherits the permissions of the user who created it, so a Project Admin's PAT carries Project Admin access to the same projects. It is also account-specific, so a user in several dbt accounts needs a separate PAT for each. A service token is different: it belongs to the account, and its permission sets are assigned when it is created. A PAT cannot create a service token. That request returns a 400 error, and an existing service token has to create the new one.
Checkpoint 8 of 8· Exam question
Which statement accurately distinguishes a dbt Cloud service token from a personal access token (PAT)?
Correct answer: A — A service token's permissions are assigned directly when it is created, while a PAT inherits the permissions of the user who generated it.
- A. Service tokens belong to the account and get their own explicitly assigned permission set, while a personal access token simply carries whatever roles and license the creating user already has.
- B. This reverses the actual constraint: on Developer and Starter plans it is the service token that is limited to Semantic Layer access, while PAT scope follows the user's own permissions rather than being universally unrestricted.
- C. This swaps the two roles: a personal access token is the one that acts on behalf of the creating user, while a service token represents the account itself rather than any individual.
- D. A personal access token cannot be used to create a service token through the API and returns a client error when attempted, so this capability does not exist in either direction.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.To rotate a token safely, delete the compromised or old token first and then create a new one.Why is that wrong?
Create the new token with the same permissions, swap it into every system, and delete the old one only afterwards. Otherwise integrations fail in the gap.
Covered in Rotating in order: create, swap, then delete
2.Storing the Snowflake private key in an env_var lets you rotate it by changing the variable's value alone.Why is that wrong?
dbt does not support reading a private key from an environment variable. The new key has to be written into the credential's Private Key field.
Covered in Generating the new key and registering its public half
3.A service account token with enough permissions can call any API endpoint, including the ones that update user credentials.Why is that wrong?
Endpoints that create or update user credentials require user context, so they are called with a personal access token.
Covered in Choosing the token that updates credentials through the API
4.Any RSA key that worked before, including a legacy 3DES-encrypted PKCS#1 key, will keep working with dbt v2.Why is that wrong?
dbt v2 needs PKCS#8, ideally with AES-256 encryption. Legacy 3DES and headerless formats cause authentication failures.
Covered in Generating the new key and registering its public half
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“New development and deployment credentials default to key pair authentication.”
↩︎ What a key pair credential is and where it lives“For user credentials on Enterprise-tier plans, Snowflake OAuth is also available when configured on the connection.”
↩︎ What a key pair credential is and where it lives“Individual users configure their user credentials in the Credentials area of their user profile.”
↩︎ What a key pair credential is and where it lives“We recommend using PKCS#8 format with AES-256 encryption for key pair authentication with dbt v2.”
↩︎ Generating the new key and registering its public half“be sure to set the rsa_public_key for the Snowflake user to authenticate in dbt”
↩︎ Generating the new key and registering its public half“This private_key string can be in either Base64-encoded DER format, representing the key bytes, or in plain-text PEM format.”
↩︎ Generating the new key and registering its public half“To successfully fill in the Private Key field, you must include commented lines.”
↩︎ Generating the new key and registering its public half“The Snowflake user or service account that dbt v2 connects as must be able to run dbt workloads”
↩︎ Generating the new key and registering its public half“dbt gets a JWT token valid for only 60 seconds.”
↩︎ Errors that follow a bad swap“The public key was not entered correctly in Snowflake.”
↩︎ Errors that follow a bad swap“Specifying a private key using an environment variable (for example, {{ env_var('DBT_PRIVATE_KEY') }}) is not supported.”
↩︎ Exam trap 2“dbt v2 doesn't support legacy 3DES encryption or headerless key formats.”
↩︎ Exam trap 4“Configure deployment environment (Production, Staging, General) credentials globally in the Connections area of Account settings.”
↩︎ Checkpoint“Specifying a private key using an environment variable (for example, {{ env_var('DBT_PRIVATE_KEY') }}) is not supported.”
↩︎ Prediction“This could be because of mistakes like not copying correctly, missing dashes, or leaving out commented lines.”
↩︎ Checkpoint - 2.https://docs.getdbt.com/docs/platform/about-profilesOfficial docs
“Profiles don't apply to development environments because of the unique configurations and individual credentials applied.”
↩︎ What a key pair credential is and where it lives“You can manage profiles programmatically using our API documentation.”
↩︎ What a key pair credential is and where it lives - 3.https://docs.getdbt.com/docs/dbt-apis/authenticationOfficial docs
“Use PATs to authenticate to any API endpoint that requires user context (for example, endpoints to create and update user credentials).”
↩︎ Choosing the token that updates credentials through the API“You should use service tokens broadly for any production workflow where you need a service account.”
↩︎ Choosing the token that updates credentials through the API“Use PATs to authenticate to any API endpoint that requires user context (for example, endpoints to create and update user credentials).”
↩︎ Exam trap 3 - 4.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.”
↩︎ Choosing the token that updates credentials through the API“Ensure the new token has the same permissions as the old one.”
↩︎ Rotating in order: create, swap, then delete“Copy the new token and replace the old one in your systems.”
↩︎ Rotating in order: create, swap, then delete“Click the + Create service token button to generate a new token.”
↩︎ Rotating in order: create, swap, then delete“All service token traffic is subject to IP restrictions.”
↩︎ Rotating in order: create, swap, then delete“you should add your third-party integration CIDRs (network addresses) to your allowlist.”
↩︎ Rotating in order: create, swap, then delete“Service account tokens enable you to securely authenticate with the dbt API by assigning each token a narrow set of permissions”
↩︎ Errors that follow a bad swap“Only take this action after the new token is in place to avoid service disruptions.”
↩︎ Key concept“Only take this action after the new token is in place to avoid service disruptions.”
↩︎ Exam trap 1“Only take this action after the new token is in place to avoid service disruptions.”
↩︎ Checkpoint - 5.https://docs.getdbt.com/docs/dbt-apis/admin-apiOfficial docs
“Many endpoints of the Administrative API can also be called through the dbt Terraform provider.”
↩︎ Choosing the token that updates credentials through the API“In general, v3 is the recommended version to use”
↩︎ Choosing the token that updates credentials through the API - 6.https://docs.getdbt.com/docs/dbt-apis/user-tokensOfficial docs
“To do so, create a new token and delete the old one once it's in place.”
↩︎ Rotating in order: create, swap, then delete“PATs inherit the permissions of the user that created them.”
↩︎ Errors that follow a bad swap“You can't use a PAT to create a service token.”
↩︎ Errors that follow a bad swap