Connect to an API Databricks app from your local machine

You can call a Databricks app that exposes an HTTP API (for example, a FastAPI or Gradio app) directly from your local environment. This is useful for testing and for building external clients.

note

This method applies only to apps that expose APIs or endpoints. For apps that provide only a user interface or background processing, you can't connect from a local machine.

Requirements

To connect to a Databricks app from your local machine, you must meet the following requirements:

• The app must expose at least one API endpoint.
• 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 from your local machine using either the Databricks CLI or Databricks SDKs.

Generate an access token

To authenticate with your app, generate an access token using the Databricks CLI or SDKs.

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:

   CLI

   Bash

   databricks auth token --profile my-env

   Python

   Python

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

   JavaScript

   JavaScript

   const { WorkspaceClient } = require('@databricks/sdk');
   const client = new WorkspaceClient({ profile: 'my-env' });
   const token = await client.apiClient.getAccessToken();

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 a request to the app

Include the token in the Authorization header:

Bash

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     https://<workspace-url>/apps/<app-id>/<endpoint>

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 (check the app's Configure tab). CLI/SDK tools only provide basic scopes like all-apis, which may not be sufficient for user authorization or agents.

Permission denied (403 errors)

Make sure you have CAN USE permission on the app.

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.

See also

For more information, see the following resources:

• Cookbook: Connect local machine to Databricks App
• Configure permissions for your Databricks app
• Set up your Databricks Apps workspace and development environment
• Authentication for the Databricks CLI
• Databricks unified authentication
• OAuth user-to-machine (U2M) authentication