Secret scopes

Managing secrets begins with creating a secret scope. A secret scope is collection of secrets identified by a name. To access secrets using Databricks Utilities, see Secrets utility (dbutils.secrets).

A workspace is limited to a maximum of 1000 secret scopes. Contact your Databricks support team if you need more.

Note

Databricks recommends aligning secret scopes to roles or applications rather than individuals.

Overview

A Databricks-backed secret scope is stored in (backed by) an encrypted database owned and managed by Databricks. The secret scope name:

• Must be unique within a workspace.

• Must consist of alphanumeric characters, dashes, underscores, @, and periods, and may not exceed 128 characters.

The names are considered non-sensitive and are readable by all users in the workspace.

You create a Databricks-backed secret scope using the Databricks CLI (version 0.205 and above). Alternatively, you can use the Secrets API.

Scope permissions

Scopes are created with permissions controlled by secret ACLs. By default, scopes are created with MANAGE permission for the user who created the scope (the “creator”), which lets the creator read secrets in the scope, write secrets to the scope, and change ACLs for the scope. If your account has the Premium plan or above, you can assign granular permissions at any time after you create the scope. For details, see Secret ACLs.

You can also override the default and explicitly grant MANAGE permission to all users when you create the scope. In fact, you must do this if your account does not have the Premium plan or above.

Create a Databricks-backed secret scope

Secret scope names are case insensitive.

To create a scope using the Databricks CLI:

databricks secrets create-scope <scope-name>

By default, scopes are created with MANAGE permission for the user who created the scope. If your account does not have the Premium plan or above, you must override that default and explicitly grant the MANAGE permission to “users” (all users) when you create the scope:

databricks secrets create-scope <scope-name> --initial-manage-principal users

You can also create a Databricks-backed secret scope using the Secrets API.

If your account has the Premium plan or above, you can change permissions at any time after you create the scope. For details, see Secret ACLs.

Once you have created a Databricks-backed secret scope, you can add secrets.

List secret scopes

To list the existing scopes in a workspace using the CLI:

databricks secrets list-scopes

You can also list existing scopes using the Secrets API.

Delete a secret scope

Deleting a secret scope deletes all secrets and ACLs applied to the scope. To delete a scope using the CLI, run the following:

databricks secrets delete-scope <scope-name>

You can also delete a secret scope using the Secrets API.