Authentication for the Databricks CLI

note

This information applies to Databricks CLI versions 0.205 and above. The Databricks CLI is in Public Preview.

Databricks CLI use is subject to the Databricks License and Databricks Privacy Notice, including any Usage Data provisions.

This article explains how to set up authentication between the Databricks CLI and your Databricks accounts and workspaces. It assumes you already installed the Databricks CLI. See Install or update the Databricks CLI.

Before you run Databricks CLI commands, you must configure authentication for the accounts or workspaces that you plan to use. The required setup depends on whether you want to run workspace-level commands, account-level commands, or both.

To view available CLI command groups, run databricks -h. For the list of corresponding REST API operations, see Databricks REST API.

OAuth machine-to-machine (M2M) authentication

Machine-to-machine (M2M) authentication with OAuth allows services, scripts, or applications to access Databricks resources without interactive user sign-in. Instead of relying on personal access tokens (PATs) or user credentials, M2M authentication uses a service principal and an OAuth client credential flow to request and manage tokens.

To configure and use OAuth M2M authentication:

1. Complete the OAuth M2M authentication setup steps. See Authorize service principal access to Databricks with OAuth.

2. Create a Databricks configuration profile with the following fields in your .databrickscfg file.

   For account-level commands

   [<some-unique-configuration-profile-name>]
   host          = <account-console-url>
   account_id    = <account-id>
   client_id     = <service-principal-client-id>
   client_secret = <service-principal-oauth-secret>

   For workspace-level commands

   [<some-unique-configuration-profile-name>]
   host          = <workspace-url>
   client_id     = <service-principal-client-id>
   client_secret = <service-principal-oauth-secret>

To use the profile, pass it with the --profile or -p flag in CLI commands. For example:

Bash

databricks account groups list -p <profile-name>

Press Tab after --profile or -p to show a list of available profiles.

OAuth user-to-machine (U2M) authentication

With OAuth user-to-machine (U2M) authentication, you log in interactively and the CLI manages short-lived tokens on your behalf. OAuth tokens expire in under an hour, which reduces risk if a token is accidentally exposed. See Authorize user access to Databricks with OAuth.

To log in:

For account-level commands

Bash

databricks auth login --host <account-console-url> --account-id <account-id>

For workspace-level commands

Bash

databricks auth login --host <workspace-url>

The CLI guides you through a browser-based login flow. When you finish, the CLI saves the credentials as a configuration profile. You can accept the suggested profile name or enter your own.

To use the profile, pass it with the --profile or -p flag in CLI commands. For example:

Bash

databricks clusters list -p <profile-name>

Press Tab after --profile or -p to show a list of available profiles.

Authentication order of evaluation

Whenever the Databricks CLI authenticates to a Databricks workspace or account, it looks for required settings in the following order:

1. Bundle settings files, for commands run from a bundle working directory. Bundle settings files can't contain credential values directly.
2. Environment variables, as listed in this article and in Environment variables and fields for unified client authentication.
3. Configuration profiles in the .databrickscfg file.

As soon as the CLI finds the required setting, it stops searching other locations.

Examples:

• If a DATABRICKS_TOKEN environment variable is set, the CLI uses it, even if multiple tokens exist in .databrickscfg.
• If no DATABRICKS_TOKEN is set, and a bundle environment references a profile name such as dev → profile DEV, the CLI uses the credentials from that profile in .databrickscfg.
• If no DATABRICKS_TOKEN is set, and a bundle environment specifies a host value, the CLI searches for a profile in .databrickscfg with a matching host and uses its token.

Personal access token authentication (deprecated)

important

Basic authentication using a Databricks username and password reached end of life on July 10, 2024. To authenticate with Databricks account, use one of the following authentication methods instead:

• OAuth machine-to-machine (M2M) authentication
• OAuth user-to-machine (U2M) authentication

Databricks personal access token authentication uses a Databricks personal access token to authenticate the target Databricks entity, such as a Databricks user account or a Databricks service principal. See Databricks personal access token authentication.

To create a personal access token, follow the steps in Databricks personal access tokens for workspace users.