Manage personal access tokens

To authenticate to the Databricks REST API, a user can create a personal access token and use it in their REST API request. To create a personal access token, see Databricks personal access token authentication.

To create a personal access token on behalf of a service principal, see Manage tokens for a service principal.

This article explains how to manage personal access tokens in your workspace.

Overview of personal access token management

Personal access tokens are enabled by default for all Databricks workspaces.

When personal access tokens are enabled on a workspace, users with the CAN USE permission can generate personal access tokens to access Databricks REST APIs, and they can generate these tokens with any expiration date they like, including an indefinite lifetime. By default, no non-admin workspace users have the CAN USE permission, meaning that they cannot create or use personal access tokens.

As a Databricks workspace admin, you can disable personal access tokens for a workspace, monitor and revoke tokens, control which non-admin users can create tokens and use tokens, and set a maximum lifetime for new tokens.

Managing personal access tokens in your workspace requires the Premium plan.

Token management.

Enable or disable personal access token authentication for the workspace

Personal access token authentication is enabled by default for all Databricks workspaces. You can change this setting in the workspace settings page.

When personal access tokens are disabled for a workspace, personal access tokens cannot be used to authenticate to Databricks and workspace users and service principals cannot create new tokens. No tokens are deleted when you disable personal access token authentication for a workspace. If tokens are re-enabled later, any non-expired tokens are available for use.

If you want to disable token access for a subset of users, you can keep personal access token authentication enabled for the workspace and set fine-grained permissions for users and groups. See Control who can create and use tokens.

Warning

Partner Connect, partner integrations, and service principals require personal access tokens to be enabled on a workspace.

To disable the ability to create and use personal access tokens for the workspace:

  1. Go to the admin settings page.

  2. Click the Advanced tab.

  3. Click the Personal Access Tokens toggle.

  4. Click Confirm.

    This change may take a few seconds to take effect.

You can also use the REST API to disable personal access tokens for the workspace. To enable or disable the token management feature for a workspace, call the workspace configuration for tokens API (PATCH /workspace-conf). In a JSON request body, specify enableTokensConfig as true (enabled) or false (disabled).

For example, to enable personal access tokens on the workspaces:

curl -X PATCH -n \
  https://<databricks-instance>/api/2.0/workspace-conf \
  -d '{
    "enableTokensConfig": "true",
    }'

Control who can create and use tokens

Workspace admins can set permissions on personal access tokens to control which users, service principals, and groups can create and use tokens. For details on how to configure personal access token permissions, see Manage access to Databricks automation.

Set maximum lifetime of new tokens (REST API only)

Use the Workspace configuration API to manage the maximum lifetime of new tokens in this workspace.

To set the maximum lifetime for new tokens, call the Set the maximum token lifetime for new tokens API (PATCH /workspace-conf). Set maxTokenLifetimeDays to the maximum token lifetime of new tokens in days, as an integer. If you set it to zero, new tokens are permitted to have no lifetime limit.

For example:

curl -n -X PATCH "https://<databricks-instance>/api/2.0/workspace-conf" \
  -d '{
  "maxTokenLifetimeDays": "90"
  }'

Warning

This limit applies only to new tokens. To review existing tokens, see the Get tokens API.

To get the workspace’s maximum lifetime for new tokens, call the Workspace configuration API (GET /workspace-conf) and pass keys=maxTokenLifetimeDays as a query parameter. The response includes an maxTokenLifetimeDays property that is the maximum token lifetime of new tokens in days, as an integer. If it is zero, new tokens are permitted to have no lifetime limit.

For example:

curl -n -X GET "https://<databricks-instance>/api/2.0/workspace-conf?keys=maxTokenLifetimeDays"

Example response:

{
    "maxTokenLifetimeDays": "90"
}

Monitor and revoke tokens (REST API only)

Use the Token Management API to manage existing tokens in the workspace.

Get tokens for the workspace

To get the workspace’s tokens, call the Get tokens API (GET /token-management/tokens). The response includes a token_infos array. Each element represents a token and includes fields for ID (token_id), creation time (creation_time), expiry time (expiry_time), description (comment), and the user that created it (the ID created_by_id or username created_by_username).

To filter results by a user, set the request body property created_by_id (for the ID) or created_by_username (for the username). You can get a user ID from a display name using the Workspace Users API (GET /scim/v2/Users).

For example:

curl -n -X GET "https://<databricks-instance>/api/2.0/token-management/tokens" \
  -d '{
  "created_by_id": "1234567890"
  }'

Example response:

{
  "token_infos": [
    {
      "token_id": "<token-id>",
      "creation_time": 1580265020299,
      "expiry_time": 1580265020299,
      "comment": "This is for ABC division's automation scripts.",
      "created_by_id": 1234567890,
      "created_by_username": "jsmith@example.com"
    }
  ]
}

Alternatively, get a specific token using the Get a token API (GET /token-management/tokens/{token_id}).

Delete (revoke) a token

  1. Find the token ID. See Get tokens for the workspace.

  2. Call the Delete a token API (DELETE /token-management/tokens). Pass the token ID in the path.

For example:

curl -n -X DELETE "https://<databricks-instance>/api/2.0/token-management/tokens/<token-id>"