Connecting My dbt Cloud Instance

Connect dbt Cloud to automatically create status pages for your assets.

Nicholas Freund avatar
Written by Nicholas Freund
Updated this week

Why connect to dbt Cloud?

Connecting Workstream to your dbt Cloud instance allows you to manage your data incident workflow, including displaying data status pages for your critical dashboards and other data assets.

Workstream automatically can detect when your models and sources fail, will register associated incidents for your team to investigate and manage, and populate a status page for any asset that is configured as an exposure in dbt Cloud.

Workstream presents failing dashboards and data incidents in our environment insights page and notification. This gives you and your team near real-time monitoring into data quality and freshness, allowing you to more easily identify urgent issues with your assets.

How do I connect to dbt Cloud?

Please note: users may have different roles in dbt Cloud that determine access to their API. In general users must have a developer license type in order to successfully generate service tokens and set up a connection. You can read more about these roles in dbt's documentation.

You should use a service token in dbt Cloud. This helps us avoid service interruptions, and makes the connection easier to manage. You can read below for step by step instructions, or using this video.

Step 1: Generating a Service Token

Service tokens allow secure system-to-system communication between dbt Cloud and Workstream. To generate this token, please take the following steps within dbt Cloud:

  1. Login as an owner

  2. Click on the gear icon in the top right corner and select "Account Settings"

  3. On the Account Settings screen, go in the left navigation to "API tokens" and within select "Service Tokens"​

  4. Click "Create service token" on the right side above the table.

  5. Enter a name for the service token. We recommend including Workstream in the name, so the token is easily identifiable.

    Image showing naming a service token in dbt cloud
  6. After you enter a name, select the "+ Add" option under the Access section, so that you can add a new permission.

    Image pointing users to the option to add a new access token in dbt Cloud
  7. Select "Account Admin" from the "Permission Sets" dropdown, and click "Save" in the top right corner of the screen.

    Image showing the required "Account Admin" permission set in dbt Cloud
  8. You will then be redirected to a screen showing the newly generated service token. This is the only time the service token is viewable, so save it in a secure location, or keep the page available in a separate browser tab when connecting your account to Workstream.

Step 2: Providing required information to Workstream

Your connections are created and managed under the "Settings" section, available by clicking on your workspace's name in the top left corner of the screen.

Find the dbt Cloud card and click "Connect".

Video showing a user navigating to their connection settings in Workstream, and initiating a connection with dbt

The only required piece of information is your service token. Enter the service token you just created, and click "Connect" to create the connection.

Image depicting a service token entered in the service token box in Workstream's connection settings

Once you've connected, Workstream will begin importing information about your dbt Cloud sources, models, and exposures. Please allow a few minutes for this initial import to complete.

Did this answer your question?