Skip to main content
Before deploying a Superblocks App to Databricks, you must configure your Superblocks environment to support the Databricks Apps runtime. This page covers all required setup steps. If any of these steps are skipped or misconfigured, the app may deploy successfully but fail at runtime.

​
What you are setting up

A deployed Databricks App runs inside a Databricks workspace. When the app makes Databricks SQL or REST API calls, it typically relies on OAuth On Behalf Of Token Exchange so Databricks can issue the correct access token for the identity accessing the app. To support this cleanly, we recommend that customers use a dedicated data tag for Databricks Apps, along with data tag specific integration configurations for Databricks SQL and Databricks REST API.

​
Prerequisites

To configure the environment, you’ll need the following in Superblocks:

​
Step 1: Create a dedicated Databricks Apps data tag

Create a dedicated data tag in Superblocks, typically named Databricks Apps. Why this matters:
  • Databricks Apps require authentication behavior that differs from Superblocks-hosted apps
  • Data tag isolation prevents breaking existing apps by mixing incompatible auth methods
  • You can change Databricks Apps specific settings without affecting other environments
Note for Hybrid customersCreating a new data tag may require updating the tags associated with your self-hosted data-plane. Follow the tagging guide to make sure one of your containers can serve as the runtime for your Databricks App APIs.

​
Step 2: Identify the Databricks token exchange endpoint

Databricks Apps require Superblocks to exchange tokens using the Databricks OIDC token endpoint: 
https://<your-databricks-workspace>/oidc/v1/token
You will use this same token URL in both the Databricks SQL integration configuration and the Databricks REST API integration configuration for the Databricks Apps data tag.

​
Step 3: Configure Databricks SQL integrations

For each Databricks SQL integration used by your app:
  1. Add a configuration scoped to the Databricks Apps data tag
  2. Set the authentication type to OAuth Token Federation
  3. Set the subject token source to Login Identity Provider
  4. Set the Token URL to https://<your-databricks-workspace>/oidc/v1/token
This ensures SQL queries executed by the deployed app run under the expected identity when the app is running inside Databricks.

​
Step 4: Configure Databricks REST API integration

For each Databricks REST API integration used by your app:
  1. Add a configuration scoped to the Databricks Apps data tag
  2. Set authentication type to OAuth 2.0: On Behalf Of Token Exchange
  3. Set subject token source to Login Identity Provider
  4. Set Subject Token Type to urn:ietf:params:oauth:token-type:access_token
  5. Set Token URL to https://<your-databricks-workspace>/oidc/v1/token
  6. Set Scope to all-apis
  7. Under Headers add Authorization: Bearer {{ oauth.token }}
This ensures REST API calls, including Jobs, Pipelines, Unity Catalog, and Model Serving, run under the correct identity.

​
Step 5: Set the app’s Production data tag

Before deploying your app to Databricks, set the app’s Production data tag to Databricks Apps. This is required. If the Production data tag is not set correctly, the app will run with the wrong integration configuration and token exchange will fail at runtime. Learn more about how to set your app’s Production data tag.

​
Step 6: Verify the environment before deployment

 Before deploying, confirm the following:

​
Integration verification

  • Databricks SQL integration has a configuration for the Databricks Apps data tag
  • Databricks REST API integration has a configuration for the Databricks Apps data tag
  • All integrations use the Databricks OIDC token endpoint
  • Databricks REST API integration scope is all-apis
  • The Authorization Header is configured in your Databricks REST API integration

​
Data tag verification

  • The Databricks Apps data tag exists and is selected as the app’s Production data tag
  • If self-hosting, your agents are tagged to support the Databricks Apps data tag

​
Access verification

  • The Databricks identity used at runtime has access to required SQL warehouses
  • The Databricks identity used at runtime has permission to call required REST APIs

​
Next steps