Capability library / Application package

dbt package v1.0.0

dbt Cloud Administrative API v2: read jobs, runs and environments, create and update job definitions, trigger job runs (deploy-equivalent), and cancel runs.

Review state: Reviewed · Distributable: yes, digest matches the release manifest

This page describes AAES Govern’s controls. AAES Operate has private-work permissions, operational reviews and recorded-spend limits; it does not include Govern. About AAES Govern

Before you enable this package

The endpoint host 'dbt-cloud.invalid' is a reserved .invalid placeholder that fails closed until you substitute the real host in both the endpoint URLs and the egress allowlist.

Read each action's effects and exclusions below. Before installation, also read the complete package requirements, including credential issuance, scope, expiry, and provider permissions. These are deployment prerequisites, not capabilities this package supplies.

Capabilities (7)

Each capability below is one registered operation. The complete package JSON includes its exact network destination allowlist. The repository stores it at packs/dbt.json and embeds a copy in the release binary.

Risk tiers. R0 is the minimum for reads. R2 is the minimum for write, create, update, execute, and invoke. R3 is the minimum for delete, send, pay, deploy, approve, share, and transfer. Operators can raise these levels. A minimum tier does not measure the operation's business or confidentiality risk.

On supported execution paths routed through AAES Govern, the R3 actions listed below require approval by an authorized person. Bypass paths and observation-only registrations are outside that guarantee. A provider's restoration feature does not remove this approval requirement. A provider-side approval, such as approving a GitLab merge request, is also separate from AAES Govern human approval. The capability matrix shows which execution paths are implemented, restricted to lab use, or refused at startup. Live compatibility must be tested in your environment.

Field guide. Endpoint is the service address and request method. Connector is the adapter that makes the call. Custody describes how the credential is held; the credential reference identifies the value to resolve. Data class sets handling requirements: pii means personal data, financial means financial records, and internal means internal organizational data.

dbt.jobs.read v1.0.0R0

Kind
tool
Action
read
Endpoint
GET https://dbt-cloud.invalid/api/v2/accounts/ACCOUNT_ID/jobs/
Connector
http
Custody
customer_vault
Credential ref
secret-ref-dbt-service-token
Data class
internal

Read jobs.

List the job definitions in the account: names, schedules, environment references and execution settings.

The registered path covers the collection read only — single-job reads are not registered.

ACCOUNT_ID is a placeholder the deployment binds before enabling; the host is a reserved placeholder to substitute with the account's access URL.

dbt.runs.read v1.0.0R0

Kind
tool
Action
read
Endpoint
GET https://dbt-cloud.invalid/api/v2/accounts/ACCOUNT_ID/runs/
Connector
http
Custody
customer_vault
Credential ref
secret-ref-dbt-service-token
Data class
internal

Read runs.

List job runs in the account: statuses, trigger causes, git references and timing. Run records can name the user or token that triggered them; this pack registers the class as internal on the deployment's account metadata — reclassify if the deployment treats trigger attribution as personal data.

The registered path covers the collection read only; run artifact downloads are deliberately not registered (see the pack notes).

dbt.environments.read v1.0.0R0

Kind
tool
Action
read
Endpoint
GET https://dbt-cloud.invalid/api/v2/accounts/ACCOUNT_ID/environments/
Connector
http
Custody
customer_vault
Credential ref
secret-ref-dbt-service-token
Data class
internal

Read environments.

List the environments in the account: names, deployment types and connection references.

The registered path covers the collection read only. Environment records reference connections but never expose the stored warehouse credentials.

ACCOUNT_ID is a placeholder the deployment binds before enabling.

dbt.job.create v1.0.0R3

Kind
tool
Actions
create, deploy
Endpoint
POST https://dbt-cloud.invalid/api/v2/accounts/ACCOUNT_ID/jobs/
Connector
http
Custody
customer_vault
Credential ref
secret-ref-dbt-service-token
Data class
internal

Create job.

Create one job definition.

The request body is an unrestricted job spec — environment, execution steps, schedule, triggers and settings are all settable — so the registered capability carries the full create effect, and an installer's intention to create only unscheduled jobs is not a restriction the registration can enforce. A created job with an active schedule will later execute models against the data platform entirely provider-side: dbt's own scheduler fires the run, and that execution never traverses dbt.job.run.trigger or any other AAES capability, so the deploy-class effect is incurred at job-creation time and the capability declares create and deploy at the minimum R3 tier.

ACCOUNT_ID is a placeholder the deployment binds before enabling.

On supported execution paths mediated by AAES Govern, the declared irreversible actions require an authorized person’s approval. Observation-only and bypass calls cannot be stopped by this control.

dbt.job.update v1.0.0R3

Kind
tool
Actions
update, deploy
Endpoint
POST https://dbt-cloud.invalid/api/v2/accounts/ACCOUNT_ID/jobs/JOB_ID/
Connector
http
Custody
customer_vault
Credential ref
secret-ref-dbt-service-token
Data class
internal

Update job.

Update one job definition. The v2 API updates a job by POSTing to the job resource (not PUT or PATCH), and the body is an unrestricted job spec — steps, schedule and triggers are all rewritable — so the capability carries the full update effect, including pointing an existing scheduled job at different steps. Editing a scheduled job re-arms provider-side execution of whatever the new spec names: dbt's scheduler fires inside dbt Cloud without traversing dbt.job.run.trigger or any other AAES capability, so the capability declares update and deploy at the minimum R3 tier.

ACCOUNT_ID and JOB_ID are placeholders the deployment binds before enabling.

On supported execution paths mediated by AAES Govern, the declared irreversible actions require an authorized person’s approval. Observation-only and bypass calls cannot be stopped by this control.

dbt.job.run.trigger v1.0.0R3

Kind
tool
Action
deploy
Endpoint
POST https://dbt-cloud.invalid/api/v2/accounts/ACCOUNT_ID/jobs/JOB_ID/run/
Connector
http
Custody
customer_vault
Credential ref
secret-ref-dbt-service-token
Data class
internal

Trigger job run.

Trigger a run of one job. A dbt job run compiles and executes the project's models against the target data platform — it changes what the warehouse serves — so triggering is deploy-equivalent and registers the deploy action at the minimum R3 tier; deploy is one of the designated actions requiring human approval.

On supported execution paths mediated by AAES Govern, irreversible actions require approval by an authorized person; this does not prevent calls through bypass or observation-only paths.

Request limits: the trigger body is unrestricted and can override the job's saved configuration (for example the git branch and the execution steps), so the governed effect is a deploy of whatever the body names, not merely the job's stored definition — an installer's intention to send an empty body is not a restriction the registration can enforce. The run is asynchronous: this call starts it, and dbt.run.cancel governs stopping it.

ACCOUNT_ID and JOB_ID are placeholders the deployment binds before enabling.

dbt.run.cancel v1.0.0R3

Kind
tool
Action
delete
Endpoint
POST https://dbt-cloud.invalid/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/cancel/
Connector
http
Custody
customer_vault
Credential ref
secret-ref-dbt-service-token
Data class
internal

Cancel run.

Cancel a queued or running job. Already executed steps are not rolled back. Interrupting a production deployment can leave warehouse models partially built, and a new run does not undo the cancellation. The historical run record remains.

Classification: delete, minimum R3, because cancellation irreversibly terminates the run’s in-flight execution. Bind ACCOUNT_ID and RUN_ID before enabling.

On supported execution paths mediated by AAES Govern, the declared irreversible actions require an authorized person’s approval. Observation-only and bypass calls cannot be stopped by this control.

Credential reference

The credential field names a reference rather than containing credential material. Packs are designed not to contain secrets; the format checks cover only known credential formats and cannot prove that arbitrary text contains no secrets. Installing a package registers its capabilities. Configure the provider credentials, endpoints, and network access, then test the integration in your environment before enabling it.

Reference
secret-ref-dbt-service-token
Custody
customer_vault
Injection
header (Authorization)

Configure the value and injection format specified in the package. Assign responsibility for credential rotation and revocation, restrict provider permissions, and keep credential material out of logs and responses.

Complete credential requirements

A dbt service account token for the customer's own account, held in the client's own secret manager. The stored material must be the complete Authorization header value — scheme, one separating space, then the token — and the injector injects the stored value verbatim. Header format: the fetched user-tokens page explicitly shows personal access tokens used as 'Authorization: Bearer <your-token>'; the fetched service-tokens page does not state the wire scheme for service account tokens, so 'Bearer <token>' is registered here as the expected-but-unverified scheme for service tokens and must be confirmed against the live reference before enabling.

Issuance: service tokens are created in Account settings > Service Tokens by an account admin, are shown only once at creation, belong to the account rather than to any user, and carry the permission sets the issuer assigns.

Least privilege: assign the minimum permission sets for the capabilities actually enabled — dbt's own sets map cleanly (Read-only or Job Viewer for the reads, Job Admin for job create and update, Job Runner for triggering runs) — and scope them to specific projects rather than all projects where the deployment allows; Account Admin tokens have full read+write on the account and this pack does not need one.

Expiry and revocation: the reviewed documentation describes no automatic expiry — a token remains valid until it is deleted in Account settings, and dbt's rotation guidance is to create a replacement token with the same permissions, put it in place, and only then delete the old token; older tokens remain valid until deleted, so disabling the ability to create new tokens does not invalidate already-issued ones.

Rotation ownership sits with an external deployment process; the executor performs no token lifecycle itself. Personal access tokens (which inherit a human user's permissions) are documented for individual use — prefer service account tokens for this integration so access does not track one employee's account.

Executor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack.

Resources

  • dbt-cloud-account (api, internal): https://dbt-cloud.invalid/api/v2/accounts/ACCOUNT_ID

Technical package and review record

Complete provider requirements and exclusions

The endpoint host 'dbt-cloud.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD): substitute the customer's own dbt access URL before enabling — dbt serves the Administrative API from the account's unique access URL — current dbt accounts are issued cell-based prefix URLs (for example abc123.us1.dbt.com; emea.dbt.com for EMEA multi-tenant, au.dbt.com for APAC, and vanity URLs for single-tenant/VPC deployments), listed in Account settings below the Account information pane, while the legacy multi-tenant host cloud.getdbt.com is documented as slated for future removal, in every endpoint, in the resource locator and in every egress allowlist entry; the allowlist matches exactly, so all three must be substituted together, and substitution is a required deployment step.

ACCOUNT_ID, JOB_ID and RUN_ID in the endpoint paths are placeholders the deployment binds to concrete resources before enabling. Triggering a job run is treated as deploy-equivalent in this pack: a dbt job run compiles and executes the project's models against the target data platform — it changes what the warehouse serves — so dbt.job.run.trigger registers the deploy action at the minimum R3 tier, not as an ordinary execute.

This pack registers Administrative API v2 routes only: dbt documents v3 as the recommended newer API with a smaller route set, and the deployment should re-review when migrating. The interactive v2 endpoint reference (docs.getdbt.com/dbt-cloud/api-v2) is a client-side-rendered explorer that did not yield retrievable operation content in this review; the registered routes follow the long-documented v2 URL shapes (jobs, runs, environments, POST .../jobs/{id}/run/ to trigger, POST .../jobs/{id}/ to update, POST .../runs/{id}/cancel/ to cancel) and each route was verified on 2026-09-21 against the retrieved dbt documentation and corroborating official sources listed in the review block (see the review record).

Scheduled execution is provider-side: a job's cron schedule fires inside dbt Cloud and never traverses an AAES capability, which is exactly why job create and update themselves declare the deploy action — dbt.job.run.trigger governs manual API triggers only.

Excluded operations: service account token or personal access token issuance and deletion (credential lifecycle stays in Account settings under direct human control), user invitation and group or permission-set management, connections (which carry warehouse credentials — writing a connection writes the database sign-in itself), repository and git credential management, account settings and billing, audit-log access, run artifact downloads (artifacts contain compiled SQL and run results — sensitive payloads deserving their own review), the Discovery (metadata) API, the Semantic Layer API, and all v3 endpoints.

Download the complete package JSON for exact network allowlists, credential requirements, exclusions, and setup notes. Read these requirements before installation.

The full documentation review record is supplied in the evaluation package. The evaluation package runs in your environment and comes only with the paid design partnership. This page reproduces the source links and review block; the full record is available for evaluation. Discuss a design partnership to inspect it before installation.

Review block

This section reproduces the review block recorded in the pack file. The evidence and approval record is separate: for a reviewed pack, it is in the evaluation materials and in the release binary's embedded assets.

Review completed: 2026-09-22

5 sources, retrieved 2026-09-21

Current documentation links are navigation aids. They do not change the package, its historical sources or its review date. Review dates describe a documentation review, not a live integration test. No package is provider-endorsed or yet tested against a live provider tenant.

Release identity

SHA-256 of the pack file bytes: 033941b6c59f870521dff32fc0dfd1e53366b71199aa8a6205ad3edcb68df98f

Distributable: yes, digest matches the release manifest. Editing a package changes its release identity. A deployment plan checks its own file digests; it does not restore reviewed status or authenticate approval.