Authorizing access to Databricks resources
This topic discusses the basic approaches for making secured Databricks CLI or REST API calls using Databricks account credentials, such as user accounts or service principals.
Authorization for the Databricks CLI and APIs
To access a Databricks resource with the Databricks CLI or REST APIs, clients must authorize using a Databricks account. This account must have permissions to access the resource, which can be configured by your Databricks administrator or a user account with adminstrator privileges.
There are two types of accounts that you can use, depending on how you intend to access your Databricks resources:
- User account: Use this to interactively enter Databricks CLI commands or REST API calls.
- Service principal: Use this to automate Databricks CLI commands or REST API calls without human interaction.
Acquire an access token
Once you have decided on the Databricks account type, you must acquire an access token that represents the account's credentials. You provide this access token when accessing the account's resources in your scripts or code, or in interactive sessions.
Your account's credentials are represented by a secure access token, which you provide either directly or indirectly to the CLI command or API call.
To securely run a Databricks CLI command or API request that requires authorized access to an account or workspace, you must provide an access token based on valid Databricks account credentials.
The following table shows the authorization methods available to your Databricks account.
Databricks authorization methods
Because Databricks tools and SDKs work with one or more supported Databricks authorization methods, you can select the best authorization method for your use case. For details, see the tool or SDK documentation in Local development tools.
Method | Description | Use case |
|---|---|---|
OAuth token federation (Recommended) | OAuth tokens from your identity provider for users or service principals. | Enables you to authenticate to Databricks without managing Databricks secrets. |
Short-lived OAuth tokens for service principals. | Unattended authentication scenarios, such as fully automated and CI/CD workflows. | |
Short-lived OAuth tokens for users. | Attended authentication scenario, where you use your web browser to authenticate with Databricks in real time, when prompted. | |
Personal access tokens (PAT) (Not recommended) | Short-lived or long-lived tokens for users or service principals. | Only use this in cases where your target tool does not support OAuth. |
Basic authentication using a Databricks username and password reached end of life on July 10, 2024. See End of life for Databricks-managed passwords.
What authorization option should I choose?
Databricks provides two options for authorization or authentication with an access token:
- OAuth 2.0-based access tokens
- Personal access tokens (PATs)
Databricks strongly recommends you use OAuth tokens over PATs for authorization as OAuth tokens are automatically refreshed by default and do not require the direct management of the access token, improving your security against token hijacking and unwanted access.
Because OAuth creates and manages the access token for you, you provide an OAuth token endpoint URL, a client ID, and a secret you generate from your Databricks workspace instead of directly providing a token string. Choose PATs only when you are integrating a third-party tool or service that is unsupported by Databricks unified client authentication or has no OAuth support.
How do I use OAuth to authorize access to Databricks resources?
Databricks provides unified client authentication to assist you with authorization by using a default set of environment variables you can set to specific credential values. This helps you work more easily and securely since these environment variables are specific to the environment that will be running the Databricks CLI commands or calling Databricks APIs.
- For user account authorization, the authentication part of Databricks OAuth—the creation and management of access tokens—is handled for you with Databricks client unified authentication, as long as the tools and SDKs implement its standard. If they don't, you can manually generate an OAuth code verifier and challenge pair to use directly in your Databricks CLI commands and API requests. See Step 1: Generate an OAuth code verifier and code challenge pair.
- For service principal authorization, Databricks OAuth requires that the caller provide client credentials along with a token endpoint URL where the request can be authorized. (This is handled for you if you use Databricks tools and SDKs that support Databricks unified client authentication.) The credentials include a unique client ID and client secret. The client, which is the Databricks service principal that will run your code, must be assigned to Databricks workspaces. After you assign the service principal to the workspaces it will access, you are provided with a client ID and a client secret that you will set with specific environment variables.
These environment variables are:
Environment variable | Description |
|---|---|
| This environment variable is set to the URL of either your Databricks account console ( |
| Used for Databricks account operations. This is your Databricks account ID. To get it, see Locate your account ID. |
| (Service principal OAuth only) The client ID you were assigned when creating your service principal. |
| (Service principal OAuth only) The client secret you generated when creating your service principal. |
You can set these directly, or through the use of a Databricks configuration profile (.databrickscfg) on your client machine.
To use an OAuth access token, your Databricks workspace or account administrator must have granted your user account or service principal the CAN USE privilege for the account and workspace features your code will access.
For more details on configuring OAuth authorization for your client and to review cloud provider-specific authorization options, see Unified client authentication.
Authentication for third-party services and tools
If you are writing code which accesses third-party services, tools, or SDKs you must use the authentication and authorization mechanisms provided by the third-party. However, if you must grant a third-party tool, SDK, or service access to your Databricks account or workspace resources, Databricks provides the following support:
- Databricks Terraform Provider: This tool can access Databricks APIs from Terraform on your behalf, using your Databricks user account. For more details, see Provision a service principal by using Terraform.
- Git providers such as GitHub, GitLab, and Bitbucket can access Databricks APIs using a Databricks service principal. For more details, see Service principals for CI/CD.
- Jenkins can access Databricks APIs using a Databricks service principal. For more details, see CI/CD with Jenkins on Databricks.
Databricks configuration profiles
A Databricks configuration profile contains settings and other information that Databricks needs to authorize access. Databricks configuration profiles are stored in local client files for your tools, SDKs, scripts, and apps to use. The standard configuration profile file is named .databrickscfg.
For more information, see Databricks configuration profiles.