Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.delphina.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every Databricks connection requires a service account — either an OAuth app (M2M) or a personal access token. Delphina uses this for background operations like catalog refresh and knowledge extraction, and it serves as the default identity for user queries. Optionally, you can enable per-user OAuth so that interactive queries run under each user’s own Databricks identity, enforcing Unity Catalog permissions, row-level security, and column masking.

​
Authentication overview

ScenarioWithout per-user OAuthWith per-user OAuth
Interactive queries (chat, data apps)Service accountPer-user token
Scheduled workflowsService accountWorkflow owner’s token
Background jobs (catalog refresh, knowledge updates)Service accountService account

​
Connecting Databricks

​
Step 1: Gather connection details

You’ll need the following from your Databricks workspace:
FieldWhere to find itExample
HostnameWorkspace URL (without https://)dbc-abc123.cloud.databricks.com
HTTP PathSQL Warehouse > Connection details/sql/1.0/warehouses/abc123def
CatalogOptional — defaults to workspace defaultmain
SchemaOptional — defaults to defaultanalytics

​
Step 2: Choose a service account authentication method

Delphina supports two service account methods for Databricks:
Use a Databricks OAuth application with machine-to-machine (M2M) credentials. This is the recommended approach.
  1. In your Databricks account console, go to Settings > App Connections.
  2. Click Add connection.
  3. Set the application name (e.g., Delphina Service).
  4. Enable the Client credentials grant type.
  5. Generate a Client Secret.
  6. Note the Client ID and Client Secret.
Grant the service principal access to the SQL warehouse and any catalogs/schemas the agent needs to query.

​
Step 3: Create the connection in Delphina

  1. Go to Org Admin > Warehouse Connections.
  2. Click Add Connection on the target workspace.
  3. Set the Warehouse Type to Databricks.
  4. Fill in Hostname, HTTP Path, and optionally Catalog and Schema.
  5. Under Authentication, choose OAuth or Personal Access Token and enter the credentials from Step 2.
  6. Click Create Connection.

​
Step 4: Test the connection

After saving, click Test Connection in the dialog footer to verify Delphina can reach your warehouse, list tables, and access query history.

​
Per-user OAuth (optional)

Per-user OAuth is an optional layer on top of the service account. When enabled, queries run under each user’s own Databricks identity instead of the shared service account. Scheduled workflows and data app refreshes run under the token of the user who created them. The service account is still used for catalog refresh and knowledge extraction.

​
Why use per-user OAuth

  • Unity Catalog enforcement — row-level security, column masking, and table ACLs apply per user.
  • Audit trail — Databricks query logs show the actual user, not a shared service account.
  • Least privilege — users only access data their Databricks role permits.

​
Setting up per-user OAuth

​
1. Create an OAuth application in Databricks

This is a separate OAuth application from the service account M2M app (if you’re using OAuth for the service account). The per-user app uses the authorization code grant type.
  1. In your Databricks account console, go to Settings > App Connections.
  2. Click Add connection.
  3. Set the application name (e.g., Delphina User Auth).
  4. Set the redirect URI:
https://app.delphina.ai/api/oauth/databricks/callback
  1. Enable the Authorization code grant type.
  2. Set the required scope: sql.
  3. Generate a Client Secret.
  4. Note the Client ID and Client Secret.

​
2. Enable per-user OAuth in Delphina

  1. Go to Org Admin > Warehouse Connections.
  2. Edit your Databricks connection.
  3. Switch to the Authentication tab.
  4. Toggle Enable per-user OAuth.
  5. Enter the Client ID and Client Secret from the per-user OAuth application.
  6. Save the connection.

​
User experience

Once per-user OAuth is enabled:
  1. A banner appears at the top of the workspace prompting users to connect their Databricks account.
  2. Clicking Connect opens a popup to the Databricks authorization page.
  3. After authorizing, the popup closes and a confirmation toast appears.
  4. The user’s token is stored securely and refreshed automatically.
Users can manage their connections from User Settings > Data Sources, where they can see connection status, refresh tokens, or disconnect.

​
Token validation

Delphina validates per-user OAuth tokens in the background. If a token becomes invalid (e.g., revoked in Databricks), the user’s connection status updates to Needs authentication and they are prompted to re-authorize.

​
Revoking access

To revoke a user’s Delphina access to Databricks:
  • From Databricks — remove the user’s authorization from the OAuth application. Their refresh token will fail on the next validation check.
  • From Delphina — the user can click Disconnect in User Settings > Data Sources.

​
Troubleshooting

ProblemFix
Test Connection failsVerify the hostname and HTTP path are correct. Ensure the service account has access to the SQL warehouse.
”Connect” banner doesn’t appearVerify per-user OAuth is enabled on the connection and has a Client ID configured.
OAuth popup shows redirect errorConfirm the redirect URI in Databricks matches exactly: https://app.delphina.ai/api/oauth/databricks/callback
User gets “insufficient privileges”Queries run under the user’s Databricks identity — check their permissions in Unity Catalog.
Scheduled workflow failsThe workflow owner must have completed the per-user OAuth flow.
Token shows “Needs authentication” after workingThe refresh token may have been revoked in Databricks, or the OAuth app’s client secret was rotated. Have the user re-authorize.
Catalog refresh failsCatalog refresh uses the service account, not per-user tokens. Check the service account credentials on the connection.