Connect to an API Databricks app using token authentication

You can call a Databricks app that exposes an HTTP API (for example, a FastAPI or Gradio app) using OAuth 2.0 Bearer token authentication. This method works from your local development environment, external applications, and other Azure Databricks apps.

Requirements

To connect to a Databricks app using token authentication, you must meet the following requirements:

• The app must expose at least one API endpoint accessible using /api/ routes.
• You must have CAN USE permission on the app. See Configure permissions for a Databricks app.
• You must be able to generate a Azure Databricks access token using one of the supported authentication methods.

Authentication methods

Choose the authentication method that matches your connection scenario:

Local development

For connecting from your local development environment, use the Databricks CLI or SDKs with your user credentials.

1. Log in with the CLI:

   databricks auth login --host https://<workspace-url> --profile my-env
   

   Azure Databricks recommends using OAuth user-to-machine (U2M) authentication.

2. Generate an access token:

   CLI

   databricks auth token --profile my-env
   

   Python

   from databricks.sdk.core import Config
   config = Config(profile="my-env")
   token = config.oauth_token().access_token
   

External applications

For programmatic access from external applications, use service principal authentication with machine-to-machine (M2M) credentials. See Authorize service principal access to Azure Databricks with OAuth.

1. Create a service principal and obtain the client ID and secret. See Service principals.

2. Generate an access token using the Databricks SDK:

   from databricks.sdk import WorkspaceClient
   import requests
   
   # Option 1: Explicit credentials
   wc = WorkspaceClient(
       host="https://<workspace-url>",
       client_id="<service-principal-client-id>",
       client_secret="<service-principal-client-secret>"
   )
   
   # Option 2: Environment variables
   # Set DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET
   wc = WorkspaceClient()
   
   # Generate Bearer token
   headers = wc.config.authenticate()
   

From other Databricks apps

When you connect from one Databricks app to another, the app handles authentication automatically using its assigned service principal.

from databricks.sdk import WorkspaceClient
import requests

# No explicit credentials needed, uses app's service principal
wc = WorkspaceClient()
headers = wc.config.authenticate()

From an Azure Databricks notebook

To call an app API from an Azure Databricks notebook, you must exchange the notebook's internal token for an audience-scoped OAuth token, then use that token to query the app.

1. Get the app's OAuth client ID. Retrieve the ID using the Azure Databricks SDK:

   from databricks.sdk import WorkspaceClient
   
   w = WorkspaceClient()
   app_client_id = w.apps.get("<app-name>").oauth2_app_client_id
   

2. Exchange the notebook token for an audience-scoped access token:

   import requests
   
   url = "https://<workspace-url>/oidc/v1/token"
   notebook_token = (
       dbutils.notebook.entry_point.getDbutils()
       .notebook().getContext().apiToken().get()
   )
   
   data = {
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "subject_token": notebook_token,
       "subject_token_type": "urn:databricks:params:oauth:token-type:personal-access-token",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "scope": "all-apis",
       "audience": app_client_id,
   }
   
   response = requests.post(url=url, data=data)
   audience_token = response.json()["access_token"]
   

3. Use the audience_token as the Bearer token to call your app. For examples, see Send requests to the app.

Specify OAuth scopes for user authorization

If your app uses user authorization, your access token must include scopes that are a superset of the scopes configured for the app. If the token doesn't have the required scopes, requests can fail with 401 or 403 errors.

A token generated using the Databricks CLI includes the all-apis scope by default, which satisfies the user authorization requirements for any app:

databricks auth token --profile my-env

To request specific scopes instead of all-apis, you can manually request an access token with explicit scopes using a custom OAuth flow. For example, the following request explicitly requests an access token with the sql, file.files, and dashboards.genie scopes:

curl --request POST \
https://<databricks-instance>/oidc/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=authorization_code" \
--data "redirect_uri=<redirect-url>" \
--data "code_verifier=<code-verifier>" \
--data "code=<authorization-code>" \
--data "scope=sql+file.files+dashboards.genie"

For full instructions, see Manually generate OAuth U2M access tokens.

Send requests to the app

When you call your app's API endpoints, include the Bearer token in the Authorization header and replace <your-endpoint> with your app's actual API path:

CURL

curl "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>" \
     -H "Authorization: Bearer <YOUR_TOKEN>"

Python with requests

import requests

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers={"Authorization": f"Bearer {token}"}
)

Python with SDK

from databricks.sdk import WorkspaceClient
import requests

wc = WorkspaceClient()
headers = wc.config.authenticate()

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers=headers
)

Security considerations

When you connect to apps from your local environment, follow these security best practices:

• Never hardcode access tokens in your source code. Use environment variables or secure credential stores.
• Refresh tokens regularly to minimize security risks if they are compromised.
• Avoid logging access tokens or sensitive data in your application logs.

Troubleshooting

If you encounter issues when connecting to your app from a local machine, try these solutions.

Authentication failures (401 errors)

Verify the following:

• Your token is valid (run databricks auth token --profile my-env)
• Your profile is correctly configured with databricks auth login
• The token hasn't expired
• Your token includes the required OAuth scopes. Your token's scopes must be a superset of the scopes configured for the app in user authorization.

Permission denied (403 errors)

Verify the following:

• You have CAN USE permission on the app
• Your token includes the required OAuth scopes. Insufficient scopes can cause 403 errors even with valid permissions.

App not found (404 errors)

Verify the following:

• The ID and workspace URL are correct
• The app is deployed and running
• The endpoint path exists in the app

Network connectivity issues

Verify the following:

• Your network allows outbound HTTPS connections
• The *.databricksapps.com domain is accessible from your network

In addition, check if your organization uses a proxy that requires configuration.

Additional resources

For more information, see the following resources:

• Cookbook: Connect from local machine
• Cookbook: Connect from external applications
• Cookbook: Connect from other apps
• Configure permissions for a Databricks app
• Set up your Databricks Apps workspace and development environment
• Authentication for the Databricks CLI
• Databricks unified authentication