> ## Documentation Index > Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt > Use this file to discover all available pages before exploring further. # Connect Devin to Databricks > Connect Devin to Databricks with a service principal, an OAuth client secret or OIDC token federation, the Databricks CLI, and Unity Catalog grants. Devin can work inside your Databricks workspaces as an asynchronous coworker: exploring catalogs, debugging failed jobs, tuning SQL, writing and testing notebooks, and shipping changes through your normal Git workflow. This guide walks through standing that up with a dedicated Databricks service principal that Devin authenticates as, governed by Unity Catalog. The integration is built from three pieces you already control: a Databricks service principal, the Databricks CLI installed through an [environment blueprint](/onboard-devin/environment/blueprints), and (optionally) the Databricks skills plugin. Databricks, its workspaces, and every permission stay in your account. ## Choose how Devin authenticates Devin authenticates to Databricks as the service principal in one of two ways. Both use the same service principal, blueprint-installed CLI, and Unity Catalog grants; they differ only in the credential. | Path | Best for | Setup | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | [**Option A: OAuth client secret**](#option-a-oauth-client-secret) | Getting started quickly. Three Devin Secrets and a short blueprint. | Generate an OAuth secret on the service principal and store it in Devin Secrets. | | [**Option B: OIDC token federation**](#option-b-oidc-token-federation) | Expanding the integration, or any team that would rather not manage a Databricks secret. Databricks [strongly recommends](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) token federation for automated workloads because there is nothing to rotate. | Trust Devin's OIDC issuer with a federation policy; each session exchanges a short-lived Devin identity token for a Databricks OAuth token. | Start with Option A if you want Devin running against Databricks today. You can move to Option B later without touching the service principal or its grants. ## Why connect Devin to Databricks? * **Devin works where your data platform lives.** Most Databricks work is not just editing notebooks in a repo. It is checking why a job failed, reading a table's schema, running a query against a warehouse, or inspecting a pipeline. Giving Devin the CLI turns those from questions for a human into things Devin can do itself. * **One auditable identity.** Devin acts as a service principal you created, so every API call, query, and job run shows up in Databricks audit logs and Unity Catalog lineage under that identity, not under an engineer's personal token. * **Unity Catalog decides what Devin can touch.** OAuth decides whether Devin can authenticate. Unity Catalog grants and workspace permissions decide what it can read or change. You can start read-only in production, give Devin a sandbox catalog to build in, and widen scope only after you have seen how it behaves. * **A path to no stored secret.** With OIDC token federation (Option B), Devin never stores a Databricks token or client secret. Each session exchanges a 60-second Devin identity token for a short-lived Databricks OAuth token. ## Overview ``` Devin session │ Databricks CLI authenticates as the service principal │ Option A: client ID + client secret from Devin Secrets │ Option B: short-lived Devin OIDC token, matched by a federation policy ▼ Databricks issues a short-lived OAuth access token for the service principal │ ▼ Workspace APIs, SQL warehouses, jobs, Unity Catalog (limited by workspace permissions and Unity Catalog grants) ``` The setup has four parts: | Part | Where it lives | What it does | | --------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | **Service principal** | Databricks account | The identity Devin acts as. Assigned to the workspaces Devin needs. | | **Authentication** | Databricks account + Devin | **Option A:** OAuth M2M with a client secret stored in Devin Secrets. **Option B:** OIDC token federation, no stored secret. | | **Databricks CLI** | Devin blueprint | Installed into the snapshot and configured to authenticate as the service principal. | | **Permissions** | Databricks workspace + Unity Catalog | Workspace entitlements, SQL warehouse and job permissions, and catalog/schema grants. | The [Databricks skills plugin](#step-4-install-the-databricks-skills-plugin-optional) is a fifth, optional layer: it teaches Devin Databricks-specific workflows (Asset Bundles, jobs, SQL, Unity Catalog) on top of the CLI. ## Prerequisites **Databricks** * A Databricks account on AWS, Azure, or GCP with **account admin** access for the person doing setup. Creating service principals, OAuth secrets, and federation policies happens at the account level. * One or more workspaces with **Unity Catalog** enabled. This guide assumes Unity Catalog governs the data Devin should reach. * The [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/) on the admin's own machine for the account-level commands below. Any recent version works for those. Devin's copy is installed separately in Step 2. **Devin** * Permission to edit your organization's [environment blueprint](/onboard-devin/environment/blueprints) (**Settings > Environment > Blueprints**). * For Option A, permission to add [Devin Secrets](/product-guides/secrets). * For Option B, your Devin **OIDC issuer URL** and **organization ID**. Step 2 shows how to read both from a token inside a Devin session. See [Cloud Authentication with OIDC](/product-guides/oidc) for background. **Network** * Devin sessions must reach your workspace host over HTTPS (for example `https://dbc-xxxx.cloud.databricks.com`, `https://adb-xxxx.azuredatabricks.net`, or `https://xxxx.gcp.databricks.com`). If your organization uses a Devin [network policy](/product-guides/security-profiles), add the workspace host and, for account-level commands, the account host (`accounts.cloud.databricks.com`, `accounts.azuredatabricks.net`, or `accounts.gcp.databricks.com`). * For Option B, Databricks must be able to fetch Devin's JWKS at `https:///.well-known/jwks.json` over the public internet to verify token signatures. ## Step 1: Create a service principal Create a dedicated service principal for Devin rather than reusing one that other automation depends on. A dedicated principal keeps audit logs and permission reviews clean. From a machine where you are logged in to the Databricks **account** (not a workspace): ```bash theme={null} databricks account service-principals create --display-name devin-sessions ``` Record two values from the output: | Field | Used for | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `applicationId` | The OAuth **client ID**. Used in the `DATABRICKS_CLIENT_ID` secret (Option A) or the CLI profile (Option B), and in `GRANT` statements. | | `id` | The numeric service principal ID. Needed to create an OAuth secret (Option A) or attach a federation policy (Option B). | Then assign the service principal to each workspace Devin should use. You can do this in the account console under **User management → Service principals**, or with the CLI: ```bash theme={null} databricks account workspace-assignment update \ --json '{"permissions": ["USER"]}' ``` Use `USER`, not `ADMIN`. Devin does not need workspace admin. ## Step 2: Connect Devin to the service principal Follow **one** of the two options below. Each is complete on its own: it installs the Databricks CLI through a [blueprint](/onboard-devin/environment/blueprints) under **Settings > Environment > Blueprints** and configures the CLI to authenticate as the service principal from Step 1. * [**Option A: OAuth client secret**](#option-a-oauth-client-secret). Standard [OAuth M2M](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m): the service principal gets a client secret, which you store in Devin Secrets. Fastest way to get started. * [**Option B: OIDC token federation**](#option-b-oidc-token-federation). Every Devin session can mint a short-lived OpenID Connect token signed by Devin. Databricks [token federation](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) lets the service principal trust that issuer, so Devin exchanges its own identity token for a Databricks OAuth token. No Databricks secret is ever created or stored, which is why Databricks strongly recommends it for automated workloads. Personal access tokens (PATs) tied to a human user are not recommended for either option. They bypass the service principal, expire unpredictably, and attribute Devin's actions to a person. ### Option A: OAuth client secret Prefer not to manage a Databricks secret at all? Skip to [Option B: OIDC token federation](#option-b-oidc-token-federation). You can also start here and switch later: swap in the Option B blueprint, create the federation policy, then delete the OAuth secret and the `DATABRICKS_CLIENT_SECRET` Devin Secret. #### 1. Generate an OAuth secret In the account console, open the service principal from Step 1 and generate an **OAuth secret**. Set the shortest lifetime your rotation process supports (the maximum is 730 days) and restrict the secret to the API scopes Devin needs, such as `sql`, `jobs`, and `unity-catalog`. Avoid selecting all scopes. #### 2. Add the Devin Secrets In Devin, add the following as [Devin Secrets](/product-guides/secrets) on the **Secrets** tab of the blueprint you will edit next (organization or repository): | Secret | Value | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DATABRICKS_HOST` | The **workspace** URL Devin should work in, for example `https://dbc-xxxx.cloud.databricks.com` or `https://adb-xxxx.azuredatabricks.net`, with no `/api` suffix. Not the `accounts.*` host. | | `DATABRICKS_CLIENT_ID` | The service principal's `applicationId` (a UUID) from Step 1, not the numeric `id` | | `DATABRICKS_CLIENT_SECRET` | The OAuth secret you generated | The CLI selects OAuth M2M automatically when a client ID and client secret are present, so `DATABRICKS_AUTH_TYPE` is not required. Set it to `oauth-m2m` only if you want to rule out every other method explicitly. Secrets are injected as environment variables at the start of every new session, so the CLI needs no profile file. A rotated secret applies to the next new session without a rebuild. #### 3. Add the blueprint Installs the CLI only. Authentication comes entirely from the three secrets above. ```yaml theme={null} initialize: - name: Install Databricks CLI run: | sudo rm -f /usr/local/bin/databricks curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh databricks --version knowledge: - name: databricks-auth contents: | The `databricks` CLI authenticates as a service principal using the DATABRICKS_HOST, DATABRICKS_CLIENT_ID, and DATABRICKS_CLIENT_SECRET environment variables, which are provided as Devin Secrets. Do not run `databricks auth login`, do not set DATABRICKS_TOKEN, and do not ask for a personal access token. Check auth with `databricks current-user me`. Write only to the devin_dev catalog; production catalogs are read-only. Ship notebook and job changes through a pull request. ``` Do not write the secrets into a file during `initialize`; anything written there is baked into the snapshot. Do not also set `DATABRICKS_TOKEN` or leave a `~/.databrickscfg` profile in the snapshot. Conflicting credentials are the most common reason M2M authentication fails. #### 4. Build the snapshot Save the blueprint and wait for the build to show **Success**, then start a new session. Existing sessions keep the old snapshot. Continue to [Step 3](#step-3-grant-permissions). ### Option B: OIDC token federation Devin sessions mint short-lived identity tokens (`iss`, `sub`, `aud`), and a federation policy on the service principal tells Databricks to trust them. The blueprint installs the `devin-oidc` CLI, wraps `databricks` so every call carries a fresh token, and writes a profile that points at your service principal. Then you read the token's claims from a session and create a policy that matches them. Want the shortest path first? Start with [Option A](#option-a-oauth-client-secret) and come back here when you are ready to drop the stored secret. #### 1. Add the blueprint Two placeholders in the profile must be replaced with your own values: | Placeholder | Replace with | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | The **workspace** URL Devin should work in, for example `https://dbc-xxxx.cloud.databricks.com` or `https://adb-xxxx.azuredatabricks.net`, with no `/api` suffix. Not the `accounts.*` host. This is the same value as `DATABRICKS_HOST` in Option A. | | `` | The service principal's `applicationId` (a UUID) from the `databricks account service-principals create` output in Step 1. Not the numeric `id`, which is only used to attach the federation policy. | ```yaml theme={null} initialize: - uses: github.com/CognitionAI/actions/setup-devin-oidc@main - name: Install Databricks CLI run: | sudo rm -f /usr/local/bin/databricks curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh sudo mv /usr/local/bin/databricks /usr/local/bin/databricks-bin - name: Wrap the CLI so each call carries a fresh Devin OIDC token run: | sudo tee /usr/local/bin/databricks > /dev/null <<'EOF' #!/usr/bin/env bash set -euo pipefail DATABRICKS_OIDC_TOKEN="$(devin-oidc token --audience "${DATABRICKS_DEVIN_AUDIENCE:-databricks}")" export DATABRICKS_OIDC_TOKEN exec /usr/local/bin/databricks-bin "$@" EOF sudo chmod +x /usr/local/bin/databricks - name: Write Databricks CLI profile run: | cat > ~/.databrickscfg <<'EOF' [DEFAULT] host = auth_type = env-oidc client_id = audience = databricks EOF chmod 600 ~/.databrickscfg knowledge: - name: databricks-auth contents: | The `databricks` CLI is preconfigured to authenticate as a service principal through Devin OIDC token federation. Do not run `databricks auth login`, do not set DATABRICKS_TOKEN, and do not ask for a personal access token. Check auth with `databricks current-user me`. Write only to the devin_dev catalog; production catalogs are read-only. Ship notebook and job changes through a pull request. ``` | Piece | Purpose | | ---------------------- | ------------------------------------------------------------------------------------------------- | | `setup-devin-oidc` | Installs the `devin-oidc` CLI that mints Devin identity tokens ([details](/product-guides/oidc)). | | Wrapper | Devin identity tokens expire after 60 seconds, so each CLI call mints its own. | | `auth_type = env-oidc` | Pins the CLI to token federation so it never falls back to a PAT or interactive login. | | `host` / `client_id` | The workspace URL and the service principal `applicationId` from the table above. | | `audience` | The audience the wrapper requests and that you will put in the federation policy below. | | `knowledge` | Tells Devin the CLI is already authenticated so it does not attempt `databricks auth login`. | The profile contains no secret, so it is safe to write during `initialize`. If you are switching from Option A, remove the `DATABRICKS_CLIENT_SECRET` Devin Secret once the policy below is in place so the CLI does not see two credentials. #### 2. Build the snapshot Save the blueprint and wait for the build to show **Success**. Nothing in the blueprint depends on the federation policy you create next, so you will not need to rebuild afterwards. #### 3. Create the federation policy With the blueprint built, Devin sessions can mint identity tokens. Use one to read the exact claims Databricks must trust, then create a federation policy on the service principal that matches them. Start a new Devin session and ask it to run the following. It prints only the token's identity claims, never the token itself. ```bash theme={null} devin-oidc token --audience databricks | python3 -c ' import sys, json, base64 p = sys.stdin.read().strip().split(".")[1] c = json.loads(base64.urlsafe_b64decode(p + "==")) print(json.dumps({k: c[k] for k in ("iss", "sub", "aud")}, indent=2))' ``` Expected shape: ```json theme={null} { "iss": "https://app.devin.ai", "sub": "org_id:", "aud": "databricks" } ``` On enterprise deployments `iss` is your custom Devin URL (for example `https://yourcompany.devinenterprise.com`). Copy `iss` and `sub` exactly as printed. Do not paste the raw token into tickets or documents; it is a bearer credential for the next 60 seconds. Save this as `devin-federation-policy.json`, substituting the values from the previous step: ```json theme={null} { "description": "Allow Devin sessions to authenticate as the devin-sessions service principal", "oidc_policy": { "issuer": "https://", "audiences": ["databricks"], "subject": "org_id:" } } ``` All three fields are exact-match: * `issuer` must equal the token's `iss`, including the scheme and with no trailing slash. * `audiences` must include the audience Devin requests (`databricks` in this guide). * `subject` must equal the token's `sub`. The default subject is your organization ID, so every session in the organization can authenticate as this principal. This is the right granularity for Databricks because federation policies match the subject as a literal string. Per-session claims such as `devin_id` change every session and cannot be matched by a static policy. Leave `subject_claim`, `jwks_uri`, and `jwks_json` unset. Databricks defaults to the `sub` claim and discovers the JWKS from the issuer's `/.well-known/openid-configuration`. ```bash theme={null} databricks account service-principal-federation-policy create \ --policy-id devin-sessions \ --json @devin-federation-policy.json ``` Confirm it exists: ```bash theme={null} databricks account service-principal-federation-policy list ``` The profile the blueprint wrote already points at this service principal, so no rebuild is needed. Continue to [Step 3](#step-3-grant-permissions). ### Rebuilds and version pinning Both the Databricks install script and `setup-devin-oidc@main` track their upstream `main` branches, so a full build picks up new releases; a [differential build](/onboard-devin/environment/differential-builds) skips `initialize` and keeps the versions already in the snapshot until the blueprint changes. If you need reproducible builds, fetch the installer from a release tag instead of `main` (for example `.../databricks/setup-cli/v1.17.0/install.sh`), which installs exactly that CLI version, and pin the action to a commit SHA (`setup-devin-oidc@`). ## Step 3: Grant permissions Authentication only proves who Devin is. What Devin can see or change is decided by workspace permissions and Unity Catalog grants, which you can adjust at any time without touching the blueprint. Start with the smallest profile that fits the work and expand deliberately. ### Permission profiles | Profile | Typical work | Unity Catalog grants | Workspace permissions | | ------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | **Explore** (start here) | Answer questions about data, document schemas, investigate failed jobs, propose query fixes in a PR | `USE CATALOG`, `USE SCHEMA`, `SELECT`, `BROWSE` on production catalogs; `READ VOLUME` where Devin needs files | `CAN USE` on one SQL warehouse; `CAN VIEW` on the jobs and pipelines Devin should investigate | | **Build** | Prototype tables, functions, and notebooks in a sandbox; run tests against real read-only data | Explore grants on production, plus ownership of (or `ALL PRIVILEGES` on) a dedicated `devin_dev` catalog or schema | Explore permissions, plus `CAN MANAGE RUN` on sandbox jobs and a restrictive cluster policy if Devin may start compute | | **Operate** | Rerun or repair specific production jobs after Explore and Build are proven | Explore grants, plus `MODIFY` on the specific tables a job writes | `CAN MANAGE RUN` on the specific jobs, granted per job rather than workspace-wide | Grant statements target the service principal by its application ID: ```sql theme={null} -- Explore: read-only on the production analytics catalog GRANT USE CATALOG, BROWSE ON CATALOG analytics TO ``; GRANT USE SCHEMA, SELECT ON SCHEMA analytics.gold TO ``; GRANT READ VOLUME ON VOLUME analytics.gold.landing TO ``; -- Build: a sandbox catalog Devin owns, isolated from production CREATE CATALOG IF NOT EXISTS devin_dev; ALTER CATALOG devin_dev OWNER TO ``; ``` If you prefer group-based administration, add the service principal to a group such as `devin-agents` and grant to the group instead. Code changes should still flow through pull requests. Devin can read production data to understand a problem and validate a fix in the sandbox, but the notebook, job definition, or Asset Bundle change lands through your normal review process, not by editing production directly. ## Step 4: Install the Databricks skills plugin (optional) Databricks publishes [Agent Skills](https://github.com/databricks/databricks-agent-skills) that teach coding agents Databricks workflows: Asset Bundles, jobs, SQL, Unity Catalog, and Spark. Installing them as a Devin [plugin](/product-guides/plugins) gives Devin that know-how on top of the CLI. 1. Open **Customize → Plugins**, choose **Add plugin → From repository**. 2. Enter the repository `databricks/databricks-agent-skills` and the subdirectory `plugins/databricks/claude`. The plugin manifest lives in that subfolder, so installing from the repository root reports **No plugin manifest found**. 3. Install at the **Organization** scope if you used an organization blueprint in Step 2. If you used a repository blueprint, declare the plugin in that repository's `.devin/config.json` instead (see [inheritance and levels](/cli/extensibility/plugins/overview#inheritance-and-levels)) so only sessions that have the CLI also get the skills. 4. [Pin the plugin to a commit](/product-guides/plugins#pinning-a-plugin) once it is working so upstream changes do not land in your sessions unreviewed. The plugin's core skill recommends running `databricks auth login` to set up a profile. That interactive browser flow cannot complete in an unattended Devin session and is not needed here; the `knowledge` entry in Step 2 tells Devin the CLI is already authenticated. ## Step 5: Verify Start a new session (after the blueprint build succeeds) and ask Devin to run: ```bash theme={null} databricks --version databricks current-user me ``` `current-user me` should return the service principal, with `userName` equal to its application ID. To confirm which authentication method the CLI chose: ```bash theme={null} databricks auth describe ``` For Option A this reports `oauth-m2m`; for Option B, `env-oidc`. Successful authentication does not mean Devin can reach your data. Confirm that the grants from Step 3 apply: ```bash theme={null} databricks catalogs list databricks warehouses list databricks grants get catalog ``` Replace `` with a catalog you granted in Step 3 (the examples there use `analytics`). Then ask Devin to run a small read-only query against a warehouse it has `CAN USE` on, and, if you set up a Build profile, to create and drop a table in `devin_dev`. A query against a production table that Devin has no `SELECT` on should fail; that failure is the permission boundary working. ## Troubleshooting | Symptom | Applies to | Cause and fix | | ----------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Errors about conflicting credentials or more than one auth method | Option A | Remove `DATABRICKS_TOKEN`, `DATABRICKS_USERNAME`, and any `~/.databrickscfg` profile. The CLI refuses to guess when more than one auth method is configured. | | `DATABRICKS_OIDC_TOKEN` not set or empty | Option B | The wrapper was bypassed or not installed. Confirm `which databricks` resolves to the wrapper and that `devin-oidc token --audience databricks` succeeds on its own. | | `invalid_grant` or an error mentioning the subject | Option B | Policy `subject` does not exactly equal the token `sub`. Rerun the claims script from Step 2 and compare character by character. | | Error mentioning the audience | Option B | Policy `audiences` does not include the audience the wrapper requests. Both default to `databricks`; keep them identical. | | Error mentioning the issuer, JWKS, or signature | Option B | `issuer` has a typo (trailing slash, `http`, wrong host) or Databricks cannot reach `https:///.well-known/jwks.json`. Load that URL from outside your network to confirm it is public. | | Token expired | Option B | Devin identity tokens live for 60 seconds. Use the wrapper rather than minting a token manually. | | CLI does not recognize `env-oidc` | Option B | The snapshot has an old CLI (or the legacy Python `databricks-cli` package). Remove the old package from the blueprint and rebuild. | | Authenticated but `catalogs list` is empty or a query is denied | Both | The principal is authenticated but not authorized. Check the workspace assignment (Step 1) and the Unity Catalog grants (Step 3) with `databricks grants get catalog `. | | Connection timeouts or DNS failures | Both | The workspace host is not reachable from Devin. Add it (and the account host, if needed) to your Devin [network policy](/product-guides/security-profiles). | ## Support For Databricks-side setup (service principals, OAuth secrets, federation policies, Unity Catalog), see the [Databricks authentication documentation](https://docs.databricks.com/aws/en/dev-tools/auth/) (switch to the Azure or GCP edition as needed). For Devin-side setup (blueprints, OIDC, plugins, network policy), contact [support@cognition.ai](mailto:support@cognition.ai) or your account team.