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

# Superblocks setup for Databricks runtime

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:

* Permission to [create and manage data tags](/admin/environments)
* Permission to manage the Databricks Integrations your application uses

## Step 1: Create a dedicated Databricks Apps data tag

Create a dedicated [data tag](/admin/environments) 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

<Warning>
  **Note for Hybrid customers**

  Creating 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.
</Warning>

## 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](https://docs.superblocks.com/development-lifecycle/build/data-tags).

## 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

* Learn how [Authentication](/hosting/databricks-apps/authentication) works for Databricks Apps
* [Deploy your app to Databricks Apps](/hosting/databricks-apps/deploy)