Secrets in Unity Catalog

Preview

This feature is in Public Preview.

This page describes how to create, read, govern, and manage secrets in Unity Catalog. A Unity Catalog secret is a securable object that stores sensitive material, such as a password, token, or API key. Your notebooks and jobs can reference the secret without exposing the value in code.

Unity Catalog secrets use the three-level namespace (catalog.schema.secret) and are available across the workspaces attached to a metastore. Unity Catalog privileges govern them. This enables you to apply the same access model and auditing that you use for other data assets to your secrets.

note

Unity Catalog secrets are distinct from workspace-level Databricks secrets, which are organized into secret scopes. Use Unity Catalog secrets when you want to govern secrets with Unity Catalog privileges and reference them with the three-level namespace.

How Unity Catalog secrets work

A Unity Catalog secret is a securable object under a schema, with the fully qualified name catalog.schema.secret. Like other Unity Catalog securable objects, secrets support privilege inheritance from the catalog and schema. For more information about securable objects and inheritance, see Unity Catalog securable objects reference.

You can use a Unity Catalog secret in the following ways:

• Retrieve the value in code. With READ SECRET access, users can retrieve a secret value from notebooks and jobs using dbutils or the Unity Catalog REST API. They can then use it to authenticate with external systems or to encrypt and decrypt data.
• Reference the value from Unity Catalog objects. Unity Catalog objects, such as Unity Catalog connections, can reference a secret by name so that an integration can use the secret without granting users access to the value. Depending on the object, referencing a secret requires either REFERENCE SECRET or READ SECRET.

Databricks stores Unity Catalog secret values encrypted and applies secret redaction to reduce accidental exposure in outputs and logs. To rotate a secret, periodically update its value in the UI or with the Unity Catalog REST API.

Privileges for Unity Catalog secrets

The following privileges govern secrets. You can grant them at the catalog, schema, or individual secret level, and they follow Unity Catalog privilege inheritance.

Privilege	Description
CREATE SECRET	Allows a user to create a secret in a schema. Granted at the catalog or schema level.
READ SECRET	Allows a user to retrieve a secret value.
WRITE SECRET	Allows a user to update a secret value.
REFERENCE SECRET	Allows a user to reference a secret, for example from a Unity Catalog connection, without access to the value.

Privilege	Description
CREATE SECRET	Allows a user to create a secret in a schema. Granted at the catalog or schema level.
READ SECRET	Allows a user to retrieve a secret value.
WRITE SECRET	Allows a user to update a secret value.
REFERENCE SECRET	Allows a user to reference a secret, for example from a Unity Catalog connection, without access to the value.

To create a secret in a schema, a user must have USE CATALOG permission and either own the schema or have CREATE SECRET and USE SCHEMA on the schema. To learn how to grant privileges, see Manage privileges in Unity Catalog.

Before you begin

To use Unity Catalog secrets, you must meet the following requirements:

• The workspace must be enabled for Unity Catalog. For an introduction, see What is Unity Catalog?.
• You must access secrets from Unity Catalog-enabled compute. Databricks recommends one of the following:
  • Serverless jobs and notebooks using environment version 4 or above.
  • Classic compute in standard access mode running Databricks Runtime 17.3 LTS or above.
• To retrieve secrets with dbutils, the compute must run Databricks Runtime 17.3 LTS or above, or serverless environment version 4 or above.

Create a secret

Creating a secret requires that you have USE CATALOG permission and own the schema or have CREATE SECRET and USE SCHEMA on the schema. See Privileges for Unity Catalog secrets.

Catalog Explorer

1. In your Databricks workspace, click Catalog to open Catalog Explorer.
2. Go to the schema where you want to create the secret.
3. Click Create > Secret.
4. Enter a name and value. Optionally, add a comment and an expiration date. If a secret expires, Catalog Explorer shows a warning.
5. Click Create.

REST API

Run the following cURL command using the /api/2.1/unity-catalog/secrets endpoint:

Bash

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_name": "main",
    "schema_name": "default",
    "name": "example_secret",
    "value": "your_secret_value",
    "comment": "your secret description"
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Read a secret

To read a secret value, you must have READ SECRET on the secret or on a parent catalog or schema.

Secrets utility (dbutils.secrets)

Databricks recommends dbutils to read secrets, because it applies secret redaction. This option requires Databricks Runtime 17.3 LTS or above, or serverless environment version 4 or above.

Python

# Read a specific secret
my_secret = dbutils.secrets.get(catalog="main", schema="default", key="example_secret")

For more information, see Secrets utility (dbutils.secrets).

REST API

warning

Secret values retrieved with the Unity Catalog REST API are not subject to secret redaction, though access is still recorded in audit logs. Databricks recommends dbutils instead.

To return the value, set include_value=true and read the effective_value field in the response:

Bash

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "include_value=true" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Manage permissions on secrets

Grant CREATE SECRET at the catalog or schema level to control who can create secrets. Grant READ SECRET, WRITE SECRET, or REFERENCE SECRET at the catalog, schema, or individual secret level to control access. Privilege inheritance applies. To learn more about granting and revoking privileges, see Manage privileges in Unity Catalog.

Grant the ability to create secrets

Catalog Explorer

1. In Catalog Explorer, go to the schema.

2. Click the Permissions tab.

3. Click Grant.

4. Select the principals to grant access to, then select CREATE SECRET.

   If a principal does not have USE SCHEMA, a warning prompts you to grant it. USE SCHEMA is also required to create secrets in the schema.

5. Click Confirm.

SQL

SQL

GRANT CREATE SECRET, USE SCHEMA ON SCHEMA main.default TO `user@example.com`;

REST API

Run the following cURL command using the /api/2.1/unity-catalog/permissions/schema/{schema_name} endpoint:

Bash

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["CREATE_SECRET", "READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/schema/{schema_name}"

Grant access to a secret

Catalog Explorer

1. In Catalog Explorer, go to the secret and click it.
2. Click the Permissions tab.
3. Click Grant.
4. Select the principals and the privileges to grant, then click Confirm.

SQL

SQL

GRANT READ SECRET ON SECRET main.default.example_secret TO `user@example.com`;

REST API

Run the following cURL command using the /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} endpoint:

Bash

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret}"

List, update, and delete secrets

List secrets

Catalog Explorer

1. In Catalog Explorer, go to the schema.
2. In the Overview pane, click Secrets to see all secrets in the schema.

Secrets utility (dbutils.secrets)

Python

# List all secrets in a schema
all_secrets = dbutils.secrets.list(catalog="main", schema="default")

REST API

List requests use page_size to control the number of results:

Bash

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Update a secret

To update a secret value, you must have WRITE SECRET on the secret.

Catalog Explorer

1. In Catalog Explorer, go to the schema and click Secrets in the Overview pane.
2. Click the secret to update.
3. In the top-right corner, click the kebab menu (vertical dots) and select Edit.
4. Enter a new value or expiration date, then click Confirm.

REST API

Update requests require the update_mask parameter. Only fields included in both update_mask and the request body are updated:

Bash

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value": "new_secret_value"}' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret?update_mask=*"

Delete a secret

Catalog Explorer

1. In Catalog Explorer, go to the schema and click Secrets in the Overview pane.
2. Click the secret to delete.
3. In the top-right corner, click the kebab menu (vertical dots) and select Delete.
4. Enter the full name of the secret, then click Delete.

REST API

Bash

curl -X DELETE \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Audit events for Unity Catalog secrets

The system.access.audit system table records events related to Unity Catalog secrets. For example, to see all secret events for a user on a specific date, run the following query:

SQL

SELECT * FROM system.access.audit
WHERE
  user_identity.email = "user@example.com"
  AND event_date = "2026-02-20"
  AND service_name = "unityCatalog"
  AND action_name LIKE "%Secret%";

For more information about audit logs, see Audit log system table reference.

Encrypt secret values with customer-managed keys

By default, Databricks encrypts secret values with Databricks-managed keys. You can instead use customer-managed keys (CMK). If you enable the CMK-encrypted managed catalog feature and attach a CMK configuration to your account, Databricks uses the CMK to encrypt secret values. For more information, see Customer-managed keys for Unity Catalog.

Limitations

Unity Catalog secrets have the following limitations:

• No SQL warehouses. Unity Catalog secrets are not supported on SQL warehouses. They require Databricks Runtime 17.3 LTS or above on Unity Catalog-enabled compute, or serverless.
• No global discovery. Unity Catalog secrets do not appear in global search.
• No BROWSE permission support. BROWSE on a catalog doesn't apply to Unity Catalog secrets. To make a secret discoverable, grant READ SECRET or REFERENCE SECRET on the individual secret or its schema.
• No init scripts. You cannot use Unity Catalog secrets in global or cluster init scripts. Databricks recommends using dedicated features instead of init scripts where possible.
• No information schema. Information schema tables for secrets are not yet available. Use Catalog Explorer or the REST API for discovery.
• dbutils runtime scope. dbutils retrieval is supported on Databricks Runtime-backed notebooks and jobs. Non-Databricks Runtime contexts, such as remote development or compiled JAR run modes, are not supported.
• OAuth API scope. The Unity Catalog secrets API is accessible only with the unity-catalog OAuth API scope. Use the secrets API scope only for workspace-level Databricks secrets.
• Quota limits. Up to 100 secrets per schema and 1,000 per metastore.