Choose how Atlan connects to dbt
Compare the two ways Atlan can read your dbt metadata - the dbt Cloud API with a token, or dbt output files in a cloud storage bucket for dbt Core.
Atlan can read your dbt metadata two ways: by calling the dbt Cloud API with a token, or by reading the files dbt produces from a cloud storage bucket (for dbt Core). This page helps you pick the right one in about two minutes - before you touch any tokens or cloud configuration.
Before you start: Two facts you need
Everything below depends on knowing these. Gather them first - they determine which path applies to you.
| Fact | How to find it |
|---|---|
| Which dbt you run: dbt Cloud or dbt Core | If your team logs into a dbt website (an address like cloud.getdbt.com or xx000.us1.dbt.com) and runs jobs there, that's dbt Cloud. If dbt runs on your own machines or CI/CD pipeline (GitHub Actions, Airflow, Jenkins…), that's dbt Core. Ask whoever runs your dbt jobs. |
| Which cloud and region your Atlan tenant runs on (AWS, Azure, or GCP) | Ask your Atlan admin, or raise a support request - say "which cloud and region is my tenant hosted in, and what's its outbound IP?" You need this if anything on your side restricts access by IP address. |
Compare two methods
| dbt Cloud - API token | dbt Core - storage bucket | |
|---|---|---|
| How Atlan reads metadata | Atlan calls the dbt Cloud APIs over the internet (TLS-encrypted) using a token you create | Your dbt pipeline uploads output files (manifest.json etc.) to a bucket; Atlan reads them from there |
| What you configure | A dbt Cloud token + your dbt Cloud access URL | A bucket (yours or Atlan-managed) + read access for Atlan |
| Network path | Atlan → dbt Cloud API, from your tenant's fixed outbound IP | Atlan → your S3 / GCS / ADLS bucket, from your tenant's cloud identity |
| Who is involved | You + your dbt Cloud admin (+ Atlan support if dbt Cloud restricts by IP) | You + your cloud/infra team + Atlan support (for Atlan's identity ARN or a managed bucket) |
| Typical setup time | Under an hour (add 1–2 days if IP restrictions are involved) | Half a day to a few days (IAM approvals are usually the long pole) |
| Start here | dbt Cloud guide | dbt Core guide |
With dbt Core you can use your own bucket (AWS S3, Google Cloud Storage, or Azure Data Lake Storage) or ask Atlan to provision an Atlan-managed bucket - you get a prefix and upload credentials, and skip most of the IAM work. Both are covered in the dbt Core guide and Set up dbt Core.
Which method to pick
- You run dbt Cloud → use the API token method. It's the direct path, and the only one that also picks up dbt Cloud job/environment context.
- You run dbt Core → use the storage bucket method. There is no API to call; Atlan reads the files dbt writes. If your security team is slow to approve cross-account access, the Atlan-managed bucket option avoids that entirely.
- You run both (common during migrations) → set up one connection per flavor. See Special cases for how to avoid duplicate assets.
Most dbt connectivity failures are one of two things: dbt Cloud rejecting Atlan's IP address (when your dbt Cloud account has IP restrictions turned on - the error misleadingly mentions "token permissions"), and bucket permission errors for dbt Core (AccessDenied from S3/GCS). Both are covered step-by-step in the guides and in Troubleshooting dbt connectivity.
See also
- How dbt connectivity works: The 5-minute explainer - no cloud knowledge assumed. Read this if "IAM role" or "NAT IP" are new terms.
- Atlan Network Details: How tenant-specific values like your outbound NAT IP work, and how to get yours.
- Connect dbt Cloud with an API token: Four phases, each labeled with who performs it and how long it takes.
- Connect dbt Core via a storage bucket: Five phases covering your own bucket (S3/GCS/ADLS) or an Atlan-managed one.