Secret access control

This article describes how to configure permissions on secret scopes.


Access control is available only in the Premium plan or above. If your account does not include that plan, you must explicitly grant MANAGE permission to the users (all users) group when you create secret scopes.

Secret access control

Access control for secrets is managed at the secret scope level. The creator of a scope automatically receives MANAGE permissions on the scope. They can then assign users, service prinicpals, and groups additional permissions on the scope. Workspace admins have MANAGE permissions on all secret scopes in the workspace.

When a secret is read via a notebook using the Secrets utility (dbutils.secrets), the user’s permission is applied based on who is executing the command, and they must at least have READ permission.

Secrets permissions levels

There are three permission levels on secrets:





Read the secret scope




List secrets in the scope




Write to the secret scope



Modify permissions


Manage secrets permissions

This section describes how to manage secret access control using the What is the Databricks CLI? (version 0.205 and above). You can also use the Secrets API or Databricks Terraform provider.

Create a secret ACL

To create a secret ACL for a given secret scope using the Databricks CLI (legacy)

databricks secrets put-acl <scope-name> <principal> <permission>

Making a put request for a principal that already has an applied permission overwrites the existing permission level.

The principal field specifies an existing Databricks principal. A user is specified using their email address, a service principal using its applicationId value, and a group using its group name.

View secret ACLs

To view all secret ACLs for a given secret scope:

databricks secrets list-acls <scope-name>

To get the secret ACL applied to a principal for a given secret scope:

databricks secrets get-acl <scope-name> <principal>

If no ACL exists for the given principal and scope, this request will fail.

Delete a secret ACL

To delete a secret ACL applied to a principal for a given secret scope:

databricks secrets delete-acl <scope-name> <principal>