Skip to main content

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 Databricks apps.

note

This method applies only to apps that expose APIs or endpoints (accessible using /api/ routes). For apps that provide only a user interface or background processing, you can't connect using token authentication.

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 your Databricks app.
  • You must be able to generate a 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:

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

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

  2. Generate an access token:

    Bash
    databricks auth token --profile my-env

External applications​

For programmatic access from external applications, use service principal authentication with machine-to-machine (M2M) credentials. See Authorize service principal access to 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:

    Python
    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.

Python
from databricks.sdk import WorkspaceClient
import requests

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

Specify OAuth scopes for user authorization​

When you use the Databricks CLI or SDKs with unified authentication, as shown the previous section, the tools automatically request the basic all-apis scope. However, if your app uses user authorization, you must manually request an access token with additional scopes using a custom OAuth flow.

Make sure that your access token includes the scopes configured in Edit > User authorization. If the token doesn't have the required scopes, requests can fail with 401 or 403 errors.

For example, the following request explicitly requests an access token with the sql, file.files, and dashboards.genie scopes:

Bash
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:

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

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. CLI and SDK tools only provide basic scopes like all-apis, which might not be sufficient for 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:

Last updated on