Skip to main content

Connect dbt Cloud with API token

TL;DR

Point Atlan at your dbt Cloud account using a token - four phases including the IP-restrictions network step most guides skip.

Connect

Point Atlan at your dbt Cloud account using a token. Four phases, each labeled with who performs it. Phase 2 (the network path) is the one most guides skip - and the one behind the most frustrating support cases.

Prerequisites​

  • A dbt Cloud account with the projects you want in Atlan, and someone with admin access to it (to create a service token).
  • Every dbt job you want cataloged runs dbt docs generate (add the command to the job steps, or enable the Generate docs on run checkbox). Without it, Atlan gets no catalog.json and column metadata is missing.
  • Admin or connection admin privileges in Atlan.

Four phases at glance​

PhaseWhat happensOwnerTypical time
1. TokenCreate a token with the right permissionsdbt Cloud admin15 minutes
2. NetworkAllowlist Atlan's NAT IP if dbt Cloud restricts by IPdbt Cloud admin + Atlan support1–2 business days (ticket round-trip)
3. ConnectEnter access URL + token in Atlan, test authenticationAtlan User15 minutes
4. Scope & runPick projects/environments, set connection admins, crawlAtlan User30 minutes

Phase 1 - create token​

Owner: dbt Cloud admin

Create a service account token (recommended) in dbt Cloud with these permissions (see Set up dbt Cloud):

Your dbt Cloud planPermission set on the token
TeamRead-only access to all projects you want in Atlan
EnterpriseJob Viewer access to all projects you want in Atlan

No admin available? A personal access token (PAT) works if the person who creates it has Job Viewer access to all target projects - but it dies with that person's account, so treat it as temporary.

Also grab your access URL now

While logged into dbt Cloud, copy the address from your browser bar up to the domain—for example, https://cloud.getdbt.com or https://ab123.us1.dbt.com (single-tenant/regional accounts have their own). You'll enter it in Phase 3. Do not use any URL containing metadata.—that's the Discovery API host and Atlan's calls fail there with "Resource not found."

Phase 2 - Open network path​

Owner: dbt Cloud admin + Atlan support

Skip this phase only if you are certain your dbt Cloud account has no IP restrictions (ask your dbt admin to check Account settings → IP restrictions). If restrictions are on - increasingly common at security-conscious organizations - dbt Cloud silently rejects Atlan's calls, and the error you'll see in Atlan misleadingly blames the token.

  1. Atlan User - Raise a support ticket: "Please share the static outbound NAT IPs for tenant <tenant URL>; these need to be allowlisted in dbt Cloud IP restrictions."
  2. dbt Cloud admin - Add every IP support returns to the dbt Cloud IP-restrictions allowlist.
  3. Re-run Test Authentication in Atlan (Phase 3).
The weeks-long failure with a one-line fix

A recurring pattern: the error "Access forbidden. Please check your dbt Cloud token permissions." leads teams to spend weeks regenerating tokens with ever-higher roles - while the actual cause is dbt Cloud IP restrictions, fixed immediately by allowlisting the tenant's NAT IP. If a token with correct permissions still gets "Access forbidden," check IP restrictions before touching the token again.

Phase 3 - Connect in Atlan​

Owner: Atlan User

  1. In Atlan, open New workflow → dbt Assets and choose Cloud as the extraction method.
  2. Host Name - your dbt Cloud access URL from Phase 1, including https://. Default is https://cloud.getdbt.com; single-tenant/regional accounts enter their own URL.
  3. Authentication type - Service Account (or PAT, matching what you created).
  4. Token - paste it.
  5. Click Test Authentication.
Test resultWhat it means
SuccessHost, token, and network path all work. Continue to Phase 4.
"Access forbidden. Please check your dbt Cloud token permissions."Token permissions or IP restrictions (Phase 2). See troubleshooting.
"Resource not found. Please check your account/project/environment details."Wrong host - usually a metadata. URL. Use your account access URL.
"Authentication failed. Please check your dbt Cloud token."Token invalid for this host - wrong instance, revoked, or truncated on paste.

Phase 4 - Scope and run​

Owner: Atlan User

  1. Under dbt settings, Include/Exclude Metadata by project or environment. If you run DEV/TEST/PROD environments, scope deliberately - crawling all of them into one connection creates duplicate-looking assets (see Special cases).
  2. Set Connection Admins. If you leave it empty, nobody can manage the connection later - including you.
  3. Run once, verify assets, then schedule.

Success checklist​

  • Test Authentication passes
  • A first run completes and dbt models appear in Atlan
  • Models show columns (proves dbt docs generate is producing catalog.json)
  • You've noted where the token lives and who rotates it - see token rotation

Next steps​

Crawl dbt: Configure and run the crawler to extract metadata from dbt