Databricks
Let agents query your Databricks lakehouse and manage jobs and notebooks in a workspace.
Connect it with: API key. Databricks's own documentation: https://docs.databricks.com/aws/en/dev-tools/auth/pat.
What agents can do
Connect Databricks so the agents working your tasks can reach it. With it connected, they can:
- Run SQL on a SQL warehouse through the Statement Execution API to answer data questions.
- List catalogs, schemas and tables in Unity Catalog before writing a query or a pipeline change.
- Check the state of a job run and read its error when a nightly pipeline fails.
- Trigger an existing job after a code change has merged.
Before you start
- A Databricks workspace where personal access tokens are enabled (an admin can turn them off under Settings > Advanced > Personal access tokens).
- A user or service principal for agents, with the workspace permissions and Unity Catalog grants they need, and CAN USE on the SQL warehouse.
- A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.
Connect with Databricks
Jaah connects to Databricks with an API key, not with a sign-in button.
Connect with an API key
Find each value first:
- Workspace URL: Open your workspace in the browser and copy the address up to the first slash, for example https://dbc-a1b2c3d4-e5f6.cloud.databricks.com or https://adb-1234567890123456.7.azuredatabricks.net.
- Personal access token: In the workspace, select your user name (top right) > Settings > Developer > Access tokens > Manage > Generate new token; set a comment and lifetime, then copy the token (it starts with dapi and is shown once).
- SQL warehouse ID (optional): SQL > SQL Warehouses > your warehouse > Connection details > HTTP path; the ID is the part after /sql/1.0/warehouses/.
Then add it to Jaah:
- In Jaah, open Secrets, select New, and pick the Databricks card.
- Name the secret and choose who can use it.
- Fill in Workspace URL, Personal access token, SQL warehouse ID.
- Select Save. Jaah tests the secret straight away (see Test the connection).
Jaah encrypts what you type and never shows it again — not to you, and not to an admin.
Use your own OAuth app
Not used: Jaah connects to Databricks with an API key, not through an OAuth app.
Test the connection
Select Test on the secret. Jaah calls Databricks's API once (GET <Workspace URL>/api/2.0/preview/scim/v2/Me) with the stored values, and shows who it answered as, or which value Databricks refused and the status it answered. Jaah also tests automatically when you save or reconnect.
The last result and its time stay on the secret's page, so you can see whether it still works without testing again.
Who can use it
Every secret has an owner, and the owner decides who can use it:
- Personal — only your own tasks can use it. This is the default.
- Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
- Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.
More on owners and access: How secrets work.
Use it in an agent session
An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:
org/<name>for an organization secret,projects/<project>/<name>for one attached to a project,me/<name>for your personal one.
A key connection hands the agent its fields: workspace_url, token, warehouse_id.
Tell the agent in your task description which secret to use, for example “use the Databricks secret org/databricks”.
Manage, rotate or disconnect
Everything is on the secret's page under Secrets:
- Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at Databricks once the test passes. Steps: Replace or delete a secret.
- Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Databricks's side too, revoke or delete the key at Databricks.
Limitations
- Jaah tests by reading the token's own user. That proves the token and workspace URL are right, not that it may use a given warehouse or table.
- The Databricks SQL Statement Execution API (rather than a
SELECT 1) is what agents use to query. It needs the SQL warehouse ID, so fill it in for SQL work. - Personal access tokens expire on the lifetime chosen when they were made (workspace admins may cap it). OAuth machine-to-machine sign-in is not offered here yet.
- One secret reaches one workspace. Add a secret per workspace.
- Agents can do only what the connected Databricks account allows.
Troubleshooting
Test says Databricks rejected the personal access token (401 or 403)
Generate a new token: it may have expired, been revoked, or belong to a different workspace than the URL. An admin may also have disabled tokens for your user.
Test says the workspace cannot be reached
Use the workspace's own address (such as dbc-a1b2c3d4-e5f6.cloud.databricks.com or adb-1234567890123456.7.azuredatabricks.net), not accounts.cloud.databricks.com. A workspace behind IP access lists must allow Jaah's address.
A query fails with PERMISSION_DENIED on the warehouse
Give the token's user CAN USE on the SQL warehouse under SQL Warehouses > Permissions.
Still stuck? Select Test and read the result: it names the value Databricks refused and the status it answered.
FAQ
Should I use my own token?
Prefer a service principal's token, so the access does not end when a person leaves and its grants can be kept narrow.
Does it work on Azure and Google Cloud?
Yes. Paste that workspace's URL; the API is the same on every cloud.
Can Jaah or an admin see the key or token?
No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.
Can I connect more than one Databricks account?
Yes. Add one secret per account, each with its own name, and tell the agent which one to use.