> ## Documentation Index
> Fetch the complete documentation index at: https://resources.athenaintel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Databricks (Direct OAuth)

Connect Databricks to Athena so each member can browse catalogs and run SQL
against your warehouses as their own Databricks identity. Unity Catalog ACLs
apply unchanged, and no personal access tokens are shared.

<Info>
  Setup is two steps, done by two different people: your **Databricks account
  administrator** registers an OAuth app connection, then an **Athena workspace
  admin** saves that app once for the whole workspace. Members can only connect
  after both are done.
</Info>

## Step 1 — Register an OAuth app in Databricks (account admin)

1. Open the Databricks **Account Console**:
   * Azure: [accounts.azuredatabricks.net](https://accounts.azuredatabricks.net)
   * AWS: [accounts.cloud.databricks.com](https://accounts.cloud.databricks.com)
   * GCP: [accounts.gcp.databricks.com](https://accounts.gcp.databricks.com)
2. **Settings → App connections → Add connection**. Name it e.g. `Athena`.
3. **Redirect URLs** — add:

   ```
   https://api.athenaintel.com/api/databricks-direct/oauth/callback
   ```

   You can add multiple redirect URLs if you use more than one Athena
   environment.
4. **Scopes** — `all-apis` and `offline_access`. The second one is required so
   Athena can refresh tokens without re-prompting members.
5. **Create**. Databricks shows the **Client ID** and **Client Secret** exactly
   once — copy both immediately.
6. Copy your **Account ID** as well (top-right user menu in the Account Console).
   This is the account UUID, not the workspace org-id.

## Step 2 — Enable Databricks in Athena (workspace admin, once)

An **Athena workspace admin or owner** must add this on the Athena side for the
**entire workspace** before individual members can connect. Members cannot
configure it themselves, and the connect option stays hidden until it's saved.

Open **[Workspace Settings → Treasury →
Integrations](https://app.athenaintel.com/dashboard/workspace-settings/treasury/?tab=integrations)**,
expand **Databricks**, click **Add app**, and fill in:

| Field              | Value                                                                             |
| ------------------ | --------------------------------------------------------------------------------- |
| **Display name**   | The label members see in the connect picker                                       |
| **Workspace Host** | The bare host, e.g. `adb-1234567890.5.azuredatabricks.net` — no protocol, no path |
| **Account ID**     | Account UUID from step 1.6                                                        |
| **Client ID**      | From step 1.5                                                                     |
| **Client Secret**  | From step 1.5 (write-only — leave blank when editing to keep the current one)     |

Toggle the app on and **Save app**. You can add more than one app — for example
one per Databricks workspace — and members pick which one to authorize against.
Secrets are encrypted at rest and never returned to the browser.

## Step 3 — Members connect (each user)

1. Go to **[Integrations](https://app.athenaintel.com/dashboard/integrations/)**
   and click **Databricks → Connect**.
2. Sign in to Databricks in the popup and grant the requested scopes.
3. Athena creates a private catalog for you with a warehouse picker and SQL
   editor. Queries run as your Databricks identity.

## Troubleshooting

| Symptom                                               | Cause and fix                                                                                                                                      |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `redirect_uri_mismatch` right after the popup opens   | The callback URL isn't in the app connection's Redirect URLs list. Exact match is required.                                                        |
| Popup is blocked (especially Safari)                  | Allow pop-ups for the Athena domain and click Connect again.                                                                                       |
| `invalid_client` when running a query                 | The stored client secret no longer matches Databricks. A workspace admin should rotate the secret in the Account Console and re-save it in Athena. |
| First query hangs 30–60 seconds                       | A stopped serverless warehouse is starting. Subsequent queries reuse the warm warehouse.                                                           |
| No Databricks connect option on the Integrations page | A workspace admin hasn't completed step 2.                                                                                                         |

<Tip>
  Tokens are per-user, encrypted at rest, and refreshed automatically. Unity
  Catalog governs what each member can query — Athena adds no access of its own.
</Tip>