Skip to main content
Databricks Apps rely on Databricks for workspace authentication, then establish a Superblocks session so Superblocks can identify the user and enforce Superblocks authorization. This page explains the end to end flow and how to configure your Databricks environment to support this authentication flow.

​
End to end authentication flow

When a user opens a Superblocks App in a Databricks workspace:
  1. Databricks authenticates the user and launches the app runtime.
  2. The Databricks App backend authenticates the user with Superblocks.
  3. Superblocks establishes a session for the user and evaluates Superblocks permissions.
  4. When the app runs a query or calls Databricks APIs, Superblocks gets a scoped Databricks API token using token exchange that ensures all actions run with the correct Unity Catalog permissions of the app’s service principal or end-user
Databricks remains the source of truth for workspace identity and data access.

​
How users are authenticated with Superblocks

When a Superblocks App runs inside a Databricks workspace, Databricks is responsible for authenticating the user. Superblocks then establishes its own session so it can identify the user and enforce Superblocks authorization. To do this securely, the Databricks App backend must authenticate itself to Superblocks. This is done using a Superblocks embed token. The embed token allows Superblocks to:
  • Trust the Databricks App runtime
  • Associate the Databricks app with a Superblocks organization
  • Issue short-lived authorization credentials for accessing the app as a Superblocks user
If the embed token is missing or invalid, Superblocks cannot authenticate the user and the app will fail to load. For a detailed explanation of the Embedded App authentication flow, see the Embedded App Authentication documentation.

​
Creating an Embed Token

To create a Embed Token for authenticating with Superblocks, a Superblocks Admin should:
  1. Log in to Superblocks
  2. Navigate to Access Tokens page in Organization Settings
  3. Create a new Embed Token for Databricks Apps
  4. Copy the token value securely
Treat this token like a password. Do not commit it to source control or share it broadly.

​
Storing the token in Databricks Secrets

Once the embed token has been created, a Databricks Workspace Admin should store the token as a Databricks Secrets. This will let you securely share the token with your Databricks Apps. To store the token as a Databricks Secret:
  1. Create or select a Databricks secret scope
  2. Add a new secret with the embed token value
  3. Restrict access to the secret scope as needed
Example: 
$ databricks secrets create-scope --scope superblocks
$ databricks secrets put-secret --json '{
  "scope": "superblocks",
  "key": "embed_token",
  "string_value": "<token-value>"
}'
Only the secret name should be shared with developers. For full details on how to create and manage Databricks Secrets see Databricks Secrets docs.

​
Reference the token in the Databricks App

With the secret stored as a Databricks Secret, developers can reference the secret in their app’s app.yaml without ever seeing the token value. For example: 
env:
  - name: SUPERBLOCKS_EMBED_ACCESS_TOKEN
    valueFrom: embed_token
  To set this up, follow Databricks’s docs on how to Add a secret resource to a Databricks app.

​
Common issues

If the embed token is misconfigured, you may see:
  • The app loads in Databricks but fails to render
  • Authentication errors during app startup
  • Errors indicating the app is not authorized to embed
In most cases, these issues are resolved by verifying:
  • The embed token exists and is active
  • The token is stored correctly in Databricks secrets
  • The Databricks App references the correct secret
  • The token has not been revoked or rotated without updating Databricks

​
Next steps