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, 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	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	Expanding the integration, or any team that would rather not manage a Databricks secret. Databricks strongly recommends 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 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 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 (Settings > Environment > Blueprints).
• For Option A, permission to add Devin 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 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, 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://<your-devin-host>/.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):

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:

databricks account workspace-assignment update <WORKSPACE_ID> <SERVICE_PRINCIPAL_ID> \
  --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 under Settings > Environment > Blueprints and configures the CLI to authenticate as the service principal from Step 1.

• Option A: OAuth client secret. Standard 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. Every Devin session can mint a short-lived OpenID Connect token signed by Devin. Databricks token 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. 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 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.

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.

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 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
<your-workspace-url>	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.
<service-principal-applicationId>	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.

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      = <your-workspace-url>
      auth_type = env-oidc
      client_id = <service-principal-applicationId>
      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).
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.

1. Read your issuer and subject

   Start a new Devin session and ask it to run the following. It prints only the token’s identity claims, never the token itself.

   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:

   {
     "iss": "https://app.devin.ai",
     "sub": "org_id:<your-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.

2. Write the federation policy

   Save this as devin-federation-policy.json, substituting the values from the previous step:

   {
     "description": "Allow Devin sessions to authenticate as the devin-sessions service principal",
     "oidc_policy": {
       "issuer": "https://<your-devin-host>",
       "audiences": ["databricks"],
       "subject": "org_id:<your-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.

3. Attach the policy to the service principal

   databricks account service-principal-federation-policy create <SERVICE_PRINCIPAL_ID> \
     --policy-id devin-sessions \
     --json @devin-federation-policy.json
   

   Confirm it exists:

   databricks account service-principal-federation-policy list <SERVICE_PRINCIPAL_ID>
   

The profile the blueprint wrote already points at this service principal, so no rebuild is needed. Continue to Step 3.

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 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@<sha>).

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:

-- Explore: read-only on the production analytics catalog
GRANT USE CATALOG, BROWSE ON CATALOG analytics TO `<sp-application-id>`;
GRANT USE SCHEMA, SELECT ON SCHEMA analytics.gold TO `<sp-application-id>`;
GRANT READ VOLUME ON VOLUME analytics.gold.landing TO `<sp-application-id>`;

-- Build: a sandbox catalog Devin owns, isolated from production
CREATE CATALOG IF NOT EXISTS devin_dev;
ALTER CATALOG devin_dev OWNER TO `<sp-application-id>`;

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 that teach coding agents Databricks workflows: Asset Bundles, jobs, SQL, Unity Catalog, and Spark. Installing them as a Devin plugin 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) so only sessions that have the CLI also get the skills.
4. Pin the plugin to a commit 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:

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:

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:

databricks catalogs list
databricks warehouses list
databricks grants get catalog <catalog-name>

Replace <catalog-name> 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://<your-devin-host>/.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 <name>.
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.

Support

For Databricks-side setup (service principals, OAuth secrets, federation policies, Unity Catalog), see the Databricks authentication documentation (switch to the Azure or GCP edition as needed). For Devin-side setup (blueprints, OIDC, plugins, network policy), contact [e-mail] or your account team.