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 environment profile for Databricks Apps, along with profile 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 profile

Create a dedicated environment profile in Superblocks, typically named Databricks Apps. Why this matters:
  • Databricks Apps require authentication behavior that differs from Superblocks-hosted apps
  • Profile 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 profile 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 profile.

​
Step 3: Configure Databricks SQL integrations

For each Databricks SQL integration used by your app:
  1. Add a configuration scoped to the Databricks Apps profile
  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 profile
  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 (Deployed) profile

Before deploying your app to Databricks, set the app’s Production (Deployed) profile to Databricks Apps. This is required. If the deployed profile 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 profile.

​
Step 6: Verify the environment before deployment

 Before deploying, confirm the following:

​
Integration verification

  • Databricks SQL integration has a configuration for the Databricks Apps profile
  • Databricks REST API integration has a configuration for the Databricks Apps profile
  • 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

​
Profile verification

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

​
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