dbt Cloud User Management API Guide

Auth method: Bearer token (personal user token or service account token)

Setup steps

1. Log in to dbt Cloud and navigate to Account Settings > API Tokens.
2. For personal access: generate a User API Token under your profile.
3. For service accounts: create a Service Account Token under Account Settings > Service Tokens, assign required permissions (e.g., Account Admin or Member).
4. Pass the token in the Authorization header: 'Authorization: Token '.
5. For SCIM provisioning, generate a dedicated Service Account Token with Account Admin permissions and supply it to your IdP.

Required scopes

List users in account

• Method: GET
• URL: https://cloud.getdbt.com/api/v2/accounts/{account_id}/users/
• Watch out for: Pagination uses offset+limit; max 100 per page. Iterate using total_count from extra.pagination.

Request example

GET /api/v2/accounts/12345/users/?limit=100&offset=0
Authorization: Token <service_token>

Response example

{
  "status": {"code": 200},
  "data": [
    {"id": 1, "email": "user@example.com",
     "first_name": "Jane", "is_active": true,
     "license_type": "developer"}
  ],
  "extra": {"pagination": {"count": 1, "total_count": 1}}
}

Get single user

• Method: GET
• URL: https://cloud.getdbt.com/api/v2/accounts/{account_id}/users/{user_id}/
• Watch out for: User ID must be the dbt Cloud internal integer ID, not email.

Request example

GET /api/v2/accounts/12345/users/67/
Authorization: Token <service_token>

Response example

{
  "status": {"code": 200},
  "data": {
    "id": 67, "email": "user@example.com",
    "first_name": "Jane", "last_name": "Doe",
    "is_active": true, "license_type": "developer"
  }
}

Invite/create user

• Method: POST
• URL: https://cloud.getdbt.com/api/v2/accounts/{account_id}/invitations/
• Watch out for: Users are invited via email; they must accept before becoming active. SCIM bypasses this flow for SSO-enabled accounts.

Request example

POST /api/v2/accounts/12345/invitations/
Authorization: Token <service_token>

{"email": "newuser@example.com",
 "license_type": "developer",
 "groups": [101, 102]}

Response example

{
  "status": {"code": 201},
  "data": {
    "id": 89, "email": "newuser@example.com",
    "state": "pending"
  }
}

Update user (license/permissions)

• Method: POST
• URL: https://cloud.getdbt.com/api/v2/accounts/{account_id}/users/{user_id}/
• Watch out for: dbt Cloud v2 uses POST (not PATCH) for updates on user objects. Omitting a field may reset it; send all desired values.

Request example

POST /api/v2/accounts/12345/users/67/
Authorization: Token <service_token>

{"license_type": "read_only",
 "groups": [101]}

Response example

{
  "status": {"code": 200},
  "data": {"id": 67, "license_type": "read_only",
    "groups": [101]}
}

Deactivate/delete user

• Method: DELETE
• URL: https://cloud.getdbt.com/api/v2/accounts/{account_id}/users/{user_id}/
• Watch out for: DELETE deactivates the user rather than permanently removing them from the system. The user record is retained.

Request example

DELETE /api/v2/accounts/12345/users/67/
Authorization: Token <service_token>

Response example

{
  "status": {"code": 200},
  "data": {"id": 67, "is_active": false}
}

List groups

• Method: GET
• URL: https://cloud.getdbt.com/api/v2/accounts/{account_id}/groups/
• Watch out for: Groups control project-level permissions. Users must be assigned to groups to inherit project access.

Request example

GET /api/v2/accounts/12345/groups/
Authorization: Token <service_token>

Response example

{
  "status": {"code": 200},
  "data": [
    {"id": 101, "name": "Analysts",
     "account_id": 12345,
     "assign_by_default": false}
  ]
}

Assign user to group

• Method: POST
• URL: https://cloud.getdbt.com/api/v2/accounts/{account_id}/groups/{group_id}/
• Watch out for: Sending the users array replaces existing membership; include all desired user IDs to avoid unintended removals.

Request example

POST /api/v2/accounts/12345/groups/101/
Authorization: Token <service_token>

{"users": [67, 68]}

Response example

{
  "status": {"code": 200},
  "data": {"id": 101, "name": "Analysts",
    "users": [67, 68]}
}

List permission sets

• Method: GET
• URL: https://cloud.getdbt.com/api/v2/accounts/{account_id}/permissions/
• Watch out for: Permission sets are account-scoped or project-scoped. Project-scoped permissions require specifying project_id in the assignment.

Request example

GET /api/v2/accounts/12345/permissions/
Authorization: Token <service_token>

Response example

{
  "status": {"code": 200},
  "data": [
    {"id": 5, "name": "Account Admin",
     "state": 1, "account_id": 12345}
  ]
}

• Rate limits: dbt Cloud enforces rate limits on API requests. Official documentation states limits vary by plan but does not publish exact per-minute numbers publicly. Requests exceeding limits receive HTTP 429 responses.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 429 is returned when rate limited. Retry-After header is included. Exact limits are not published in official docs; contact dbt Labs support for Enterprise-specific limits.
• Pagination method: offset
• Default page size: 100
• Max page size: 100
• Pagination pointer: offset and limit

• Webhooks available: No
• Webhook notes: dbt Cloud supports outbound webhooks for job run events (run started, completed, errored) but does not offer webhooks for user management events such as user creation, deactivation, or group changes.
• Alternative event strategy: Poll the /users/ endpoint periodically to detect user changes, or rely on SCIM provisioning events from your IdP for user lifecycle management.
• Webhook events: job.run.started, job.run.completed, job.run.errored

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://cloud.getdbt.com/api/scim/v2/

• Supported operations: GET /Users – list users, GET /Users/{id} – get user, POST /Users – provision user, PATCH /Users/{id} – update user attributes or deactivate, DELETE /Users/{id} – deprovision user, GET /Groups – list groups, POST /Groups – create group, PATCH /Groups/{id} – update group membership, DELETE /Groups/{id} – delete group

Limitations:

• Requires Enterprise plan and SSO (SAML 2.0) to be configured before SCIM can be enabled.
• Supported IdPs: Okta and Microsoft Entra ID (Azure AD). Google Workspace and OneLogin are not officially supported.
• SCIM token must be a Service Account Token with Account Admin permissions.
• Group push from IdP maps to dbt Cloud permission groups; group names must match exactly.
• SCIM does not support provisioning project-level permission assignments directly; those must be configured in dbt Cloud after group creation.
• User deprovisioning via SCIM deactivates the user (sets active=false) but does not permanently delete the record.

Three automation patterns cover the majority of dbt Cloud identity lifecycle work via API. For provisioning individual developers, POST to /api/v2/accounts/{account_id}/invitations/ with license_type, email, and target group IDs - but note the user must accept an email invitation before their account activates.

fully silent provisioning requires SCIM on an SSO-enabled Enterprise account. For SCIM-based lifecycle automation via Okta or Microsoft Entra ID, point the IdP SCIM connector at https://cloud.getdbt.com/api/scim/v2/ using a Service Account Token.

group names must match dbt Cloud permission group names exactly (case-sensitive) or the IdP will create duplicate groups instead of mapping to existing ones.

For bulk deactivation via REST, paginate GET /users/ using offset and limit (max 100 per page), then issue DELETE /users/{user_id}/ per target - this sets is_active=false but retains the user record. for SCIM-managed accounts, always deprovision through the IdP to keep SCIM state consistent.

Provision a new developer user via REST API

1. Generate a Service Account Token with Account Admin permissions in dbt Cloud Account Settings.
2. POST to /api/v2/accounts/{account_id}/invitations/ with email, license_type='developer', and desired group IDs.
3. User receives an email invitation and must accept to activate their account.
4. After acceptance, GET /api/v2/accounts/{account_id}/users/ filtered by email to retrieve the internal user ID.
5. Optionally POST to /api/v2/accounts/{account_id}/groups/{group_id}/ to confirm group membership with the full user list.

Watch out for: The invitation flow requires user action; for fully automated provisioning without email confirmation, use SCIM with an SSO-enabled Enterprise account.

Automate user lifecycle with SCIM via Okta

1. Confirm Enterprise plan is active and SAML 2.0 SSO is configured and tested in dbt Cloud.
2. In dbt Cloud Account Settings > SCIM, generate a SCIM Service Account Token.
3. In Okta, add the dbt Cloud application from the Okta Integration Network.
4. Configure SCIM provisioning in Okta: set SCIM connector base URL to https://cloud.getdbt.com/api/scim/v2/, set auth to Bearer token using the SCIM token.
5. Enable provisioning features: Push New Users, Push Profile Updates, Push Groups, Deactivate Users.
6. Assign Okta users/groups to the dbt Cloud app; Okta will POST /Users to provision them.
7. Create matching groups in Okta and push them; group names must match dbt Cloud permission group names exactly.
8. Test by assigning a user in Okta and verifying they appear as active in dbt Cloud.

Watch out for: Group names are case-sensitive and must match exactly between Okta and dbt Cloud. Mismatches result in new groups being created rather than mapped to existing ones.

Bulk deactivate users via REST API

1. GET /api/v2/accounts/{account_id}/users/?limit=100&offset=0 and paginate through all pages to build a full user list.
2. Filter the list for users to deactivate (e.g., by email domain or last login date – note: last_login is not exposed in v2; cross-reference with IdP data).
3. For each target user, send DELETE /api/v2/accounts/{account_id}/users/{user_id}/.
4. Verify deactivation by checking is_active=false in a subsequent GET for each user.
5. Implement retry logic with exponential backoff for any HTTP 429 responses.

Watch out for: DELETE sets is_active=false but retains the user record. If the user is re-invited later, they may reactivate the same record. For SCIM-managed accounts, perform deactivation through the IdP to keep SCIM state consistent.

Several non-obvious behaviors create integration risk. The v2 API uses POST for both create and update on user objects - there is no PATCH on the v2 user endpoint, and omitting a field in an update payload may reset it to a default value; always send the full desired state.

Sending a partial users array to a group endpoint replaces the entire membership list, making partial group updates destructive by default. The last_login field is not exposed in the v2 user object, so identifying inactive users via API alone is not possible - cross-referencing IdP data or Enterprise audit logs is required.

Rate limits are not publicly documented; implement exponential backoff on HTTP 429 responses and use the Retry-After header.

Finally, dbt Cloud webhooks cover job run events only - there are no webhook events for user creation, deactivation, or group changes, so any identity graph sync must rely on polling the /users/ endpoint or on SCIM push events from the IdP.