{
  "schema": "aaes/capability-pack/1",
  "provider": "databricks",
  "version": "1.0.0",
  "description": "Databricks workspace REST API: cluster and job inventory, workspace object listing, and SQL warehouse listing.",
  "notes": "The endpoint host 'databricks-workspace.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD): substitute the customer's own Databricks workspace URL host (the documented shape is, for example, dbc-a1b2345c-d6e7.cloud.databricks.com) before enabling, in the endpoints, the resource locator and the egress allowlist — the allowlist matches exactly, so all three must be substituted together, and substitution is a required deployment step. Allowlisting the reserved.invalid host does not make an unsubstituted pack safe: an unsubstituted pack cannot resolve to a destination but has no reviewed destination, so it is not a registration of anything.\n\nThis pack registers workspace-level APIs only — the account console APIs (accounts.cloud.databricks.com, workspace provisioning, account identity) are out of scope.\n\nDocumented exclusions: this pack does not register cluster create/edit/start/terminate/delete, job create/update/reset/delete, job run triggering (POST /api/2.x/jobs/run-now), run cancel or run submit (POST /api/2.1/jobs/runs/submit, which creates an ad-hoc job and run), workspace import/export/mkdirs/delete, SQL statement execution (/api/2.0/sql/statements), warehouse create/edit/start/stop/delete, or any Unity Catalog or secret-scope surface. Run triggering is excluded deliberately: run-now executes the job's tasks under caller-supplied parameter overrides (for example notebook_params), and the http connector cannot pin the request body, so no risk tier can be honestly claimed for arbitrary job execution under caller-influenced parameters — if a deployment later enables run triggering, that is a separate purpose-built review (including the job permission level the credential needs to trigger a run).\n\nApproval classification: the inventory reads sit at R0. Every list read here describes the collection read only — single-object reads (GET /api/2.0/jobs/get, GET /api/2.0/clusters/get, GET /api/2.0/sql/warehouses/{id}) are not registered by this pack. Pagination is operation- and version-specific per Databricks documentation: the SQL warehouses list documents page_size / page_token parameters, while the Jobs 2.0 list and Workspace list operations registered here document no pagination parameters (later API versions add page_token / next_page_token); where a paginated variant applies, a complete inventory is multiple governed calls, not one.",
  "credential": {
    "secret_ref_id": "secret-ref-databricks-oauth-m2m-token",
    "custody": "customer_vault",
    "inject": "header",
    "inject_name": "Authorization",
    "note": "An access token for a dedicated least-privilege Databricks service principal, held in the client's own secret manager. The stored material must be the complete Authorization header value: the scheme 'Bearer', one separating space, then the token — 'Bearer <token>'. customer_vault is the only generally-supported production custody model here — identity_federation and customer_broker are refused at startup and inline is lab-only. The reviewed token process is OAuth M2M: an external deployment process holds the service principal's client id and secret, exchanges them at the workspace's OIDC token endpoint (POST <workspace-url>/oidc/v1/token with grant_type=client_credentials, per Databricks documentation) for a short-lived access token (Databricks documents OAuth M2M tokens as expiring, one hour by default), and writes the complete header value under this reference; renewal is the external process's job — the executor injects the stored value verbatim and performs no token lifecycle itself.\n\nRevocation is deactivating the service principal or rotating its secret; an expired or revoked token fails closed. A personal access token is the documented alternative and is deliberately not the reviewed default: PATs are long-lived user-bound credentials whose lifetime the workspace admin configures, and a user-bound credential attributes machine calls to a person.\n\nLeast privilege: grant the service principal workspace access and Can View on the jobs and clusters to be inventoried; no run-triggering permission is in scope for this pack — run triggering is not registered, and if a deployment later enables it, the job permission level the credential needs is part of that separate review.\n\nExecutor 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."
  },
  "capabilities": [
    {
      "capability_id": "databricks.clusters.list",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "databricks-workspace.invalid"
      ],
      "endpoint": "https://databricks-workspace.invalid/api/2.0/clusters/list",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-databricks-oauth-m2m-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "databricks-workspace",
      "description": "List information about all pinned and active clusters and clusters terminated within the last 30 days: names, states, node types, Spark versions and autoscaling configuration — compute inventory and posture.\n\nThe registered path covers the collection read only — single-cluster reads (GET /api/2.0/clusters/get) are not registered by this pack.",
      "requires_review": true
    },
    {
      "capability_id": "databricks.jobs.list",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "databricks-workspace.invalid"
      ],
      "endpoint": "https://databricks-workspace.invalid/api/2.0/jobs/list",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-databricks-oauth-m2m-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "databricks-workspace",
      "description": "List the jobs defined in the workspace: names, task shapes, schedules and creators — the automation inventory of the workspace.\n\nThe registered path covers the collection read only — single-job reads (GET /api/2.0/jobs/get) and run listing (GET /api/2.0/jobs/runs/list) are not registered by this pack.",
      "requires_review": true
    },
    {
      "capability_id": "databricks.workspace.objects.list",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "databricks-workspace.invalid"
      ],
      "endpoint": "https://databricks-workspace.invalid/api/2.0/workspace/list",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-databricks-oauth-m2m-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "databricks-workspace",
      "description": "List the contents of a workspace directory (notebooks, folders and other workspace objects under the caller-supplied path query parameter): names, object types and paths — the workspace's code and artifact inventory. Listing one directory is the collection read this registration covers; recursive enumeration is repeated governed calls, and object content reads (export) are not registered by this pack.",
      "requires_review": true
    },
    {
      "capability_id": "databricks.sql.warehouses.list",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "databricks-workspace.invalid"
      ],
      "endpoint": "https://databricks-workspace.invalid/api/2.0/sql/warehouses",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-databricks-oauth-m2m-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "databricks-workspace",
      "description": "List all SQL warehouses the credential has access to: names, cluster sizes, states and channel configuration — the SQL compute inventory.\n\nThe registered path covers the collection read only — single-warehouse reads (GET /api/2.0/sql/warehouses/{id}) are not registered by this pack.",
      "requires_review": true
    }
  ],
  "resources": [
    {
      "resource_id": "databricks-workspace",
      "kind": "api",
      "locator": "https://databricks-workspace.invalid/api/2.0",
      "data_class": "internal",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    }
  ],
  "review": {
    "state": "library",
    "date": "2026-09-22",
    "sources": [
      "https://docs.databricks.com/aws/en/reference/jobs-2.0-api (retrieved 2026-09-21)",
      "https://docs.databricks.com/aws/en/dev-tools/api/latest/jobs (retrieved 2026-09-21)",
      "https://docs.databricks.com/aws/en/dev-tools/api/latest/clusters (retrieved 2026-09-21)",
      "https://docs.databricks.com/aws/en/dev-tools/api/latest/workspace (retrieved 2026-09-21)",
      "https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m (retrieved 2026-09-21)",
      "https://docs.databricks.com/api/warehouses/v1/warehouse (retrieved 2026-09-21)"
    ],
    "reviewer_id": "aaes-eng"
  }
}