Secret

View as Markdown

A secret stored in Unity Catalog. Secrets are three-level namespace objects (catalog.schema.secret) that securely store sensitive credential data such as passwords, tokens, and keys.

Secret object

A secret stored in Unity Catalog. Secrets are three-level namespace objects (catalog.schema.secret) that securely store sensitive credential data such as passwords, tokens, and keys.

namestring: The name of the secret, relative to its parent schema.

ownerstring: The owner of the secret. Defaults to the creating principal on creation. Can be updated to transfer ownership of the secret to another principal.

effective_ownerstring: The effective owner of the secret, which may differ from the directly-set owner due to inheritance.

metastore_idstring: Unique identifier of the metastore hosting the secret.

create_timestring: The time at which this secret was created.

created_bystring: The principal that created the secret.

update_timestring: The time at which this secret was last updated.

updated_bystring: The principal that last updated the secret.

commentstring: User-provided free-form text description of the secret.
Constraints: [ 1 .. 65536 ] characters

full_namestring: The three-level (fully qualified) name of the secret, in the form of catalog_name.schema_name.secret_name.

catalog_namestring: The name of the catalog where the schema and the secret reside.

schema_namestring: The name of the schema where the secret resides.

valuestring: The secret value to store. This field is input-only and is not returned in responses — use the effective_value field (via GetSecret with include_value set to true) to read the secret value. The maximum size is 60 KiB (pre-encryption). Accepted content includes passwords, tokens, keys, and other sensitive credential data.
Constraints: [ 1 .. 61440 ] characters

effective_valuestring: The secret value. Only populated in responses when you have the READ_SECRET privilege and include_value is set to true in the request. The maximum size is 60 KiB.
Constraints: [ 1 .. 61440 ] characters

expire_timestring: User-provided expiration time of the secret. This field indicates when the secret should no longer be used and may be displayed as a warning in the UI. It is purely informational and does not trigger any automatic actions or affect the secret's lifecycle.

View as Markdown

The Secret object

{
  "name": "string",
  "owner": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "full_name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "value": "string",
  "effective_value": "string",
  "expire_time": "string"
}

Get GA

GET /api/2.1/unity-catalog/secrets/{full_name}

Gets a secret by its three-level (fully qualified) name.

You must be a metastore admin, the owner of the secret, or have the MANAGE privilege on the secret.

The secret value isn't returned by default. To retrieve it, you must also have the READ_SECRET privilege and set include_value to true in the request.

API scopes: unity-catalog

Parameters

full_namestringpath: The three-level (fully qualified) name of the secret (for example, catalog_name.schema_name.secret_name).

include_valuebooleanquery: Whether to include the secret value in the response. Defaults to false. Requires the READ_SECRET privilege.

Response

Returns the Secret object.

View as Markdown

Response

{
  "name": "string",
  "owner": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "full_name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "value": "string",
  "effective_value": "string",
  "expire_time": "string"
}

List GA

GET /api/2.1/unity-catalog/secrets

Lists secrets in Unity Catalog.

You must be a metastore admin, the owner of the secret, or have the MANAGE privilege on the secret.

Both catalog_name and schema_name must be specified together to filter secrets within a specific schema. Results are paginated; use the page_token field from the response to retrieve subsequent pages.

API scopes: unity-catalog

Parameters

catalog_namestringquery: The name of the catalog under which to list secrets. Both catalog_name and schema_name must be specified together.

schema_namestringquery: The name of the schema under which to list secrets. Both catalog_name and schema_name must be specified together.

page_tokenstringquery: Opaque pagination token to go to the next page based on previous query. The maximum page length is determined by a server configured value.

page_sizeint32query

Maximum number of secrets to return.

If not specified, at most 1000 secrets are returned.
If set to a value greater than 0, the page length is the minimum of this value and 1000.
If set to 0, the page length is set to 1000.
If set to a value less than 0, an invalid parameter error is returned.

Constraints: <= 1000

Response

Returns a list of Secret objects.

View as Markdown

Response

{
  "secrets": [
    {
      "name": "string",
      "owner": "string",
      "effective_owner": "string",
      "metastore_id": "string",
      "create_time": "string",
      "created_by": "string",
      "update_time": "string",
      "updated_by": "string",
      "comment": "string",
      "full_name": "string",
      "catalog_name": "string",
      "schema_name": "string",
      "value": "string",
      "effective_value": "string",
      "expire_time": "string"
    }
  ],
  "next_page_token": "string"
}

Create GA

POST /api/2.1/unity-catalog/secrets

Creates a new secret in Unity Catalog.

You must be the owner of the parent schema or have the CREATE_SECRET and USE SCHEMA privileges on the parent schema and USE CATALOG on the parent catalog.

The secret is stored in the specified catalog and schema, and the value field contains the sensitive data to be securely stored.

API scopes: unity-catalog

Request body

secretobject

The secret object to create. The name, catalog_name, schema_name, and value fields are required.

Show child attributesHide child attributes

namestring: The name of the secret, relative to its parent schema.

ownerstring: The owner of the secret. Defaults to the creating principal on creation. Can be updated to transfer ownership of the secret to another principal.

effective_ownerstring: The effective owner of the secret, which may differ from the directly-set owner due to inheritance.

metastore_idstring: Unique identifier of the metastore hosting the secret.

create_timestring: The time at which this secret was created.

created_bystring: The principal that created the secret.

update_timestring: The time at which this secret was last updated.

updated_bystring: The principal that last updated the secret.

commentstring: User-provided free-form text description of the secret.
Constraints: [ 1 .. 65536 ] characters

full_namestring: The three-level (fully qualified) name of the secret, in the form of catalog_name.schema_name.secret_name.

catalog_namestring: The name of the catalog where the schema and the secret reside.

schema_namestring: The name of the schema where the secret resides.

valuestring: The secret value to store. This field is input-only and is not returned in responses — use the effective_value field (via GetSecret with include_value set to true) to read the secret value. The maximum size is 60 KiB (pre-encryption). Accepted content includes passwords, tokens, keys, and other sensitive credential data.
Constraints: [ 1 .. 61440 ] characters

effective_valuestring: The secret value. Only populated in responses when you have the READ_SECRET privilege and include_value is set to true in the request. The maximum size is 60 KiB.
Constraints: [ 1 .. 61440 ] characters

expire_timestring: User-provided expiration time of the secret. This field indicates when the secret should no longer be used and may be displayed as a warning in the UI. It is purely informational and does not trigger any automatic actions or affect the secret's lifecycle.

Response

Returns the Secret object.

View as Markdown

Request

{
  "secret": {
    "name": "string",
    "owner": "string",
    "effective_owner": "string",
    "metastore_id": "string",
    "create_time": "string",
    "created_by": "string",
    "update_time": "string",
    "updated_by": "string",
    "comment": "string",
    "full_name": "string",
    "catalog_name": "string",
    "schema_name": "string",
    "value": "string",
    "effective_value": "string",
    "expire_time": "string"
  }
}

Response

{
  "name": "string",
  "owner": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "full_name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "value": "string",
  "effective_value": "string",
  "expire_time": "string"
}

Update GA

PATCH /api/2.1/unity-catalog/secrets/{full_name}

Updates an existing secret in Unity Catalog.

You must be the owner of the secret or a metastore admin. If you are a metastore admin, only the owner field can be changed.

Use the update_mask field to specify which fields to update. Supported updatable fields include value, comment, owner, and expire_time.

API scopes: unity-catalog

Parameters

full_namestringpath: The three-level (fully qualified) name of the secret (for example, catalog_name.schema_name.secret_name).

update_maskstringquery

The field mask specifying which fields of the secret to update.

If update_mask is "*", all fields specified in secret are updated.
If update_mask specifies one or more fields, only those fields are updated. Each specified field must be set in secret. Supported fields: value, comment, owner, expire_time. To change the secret name, delete and recreate the secret.

Request body

secretobject

The secret object containing the fields to update. Only fields specified in update_mask will be updated.

Show child attributesHide child attributes

namestring: The name of the secret, relative to its parent schema.

ownerstring: The owner of the secret. Defaults to the creating principal on creation. Can be updated to transfer ownership of the secret to another principal.

effective_ownerstring: The effective owner of the secret, which may differ from the directly-set owner due to inheritance.

metastore_idstring: Unique identifier of the metastore hosting the secret.

create_timestring: The time at which this secret was created.

created_bystring: The principal that created the secret.

update_timestring: The time at which this secret was last updated.

updated_bystring: The principal that last updated the secret.

commentstring: User-provided free-form text description of the secret.
Constraints: [ 1 .. 65536 ] characters

full_namestring: The three-level (fully qualified) name of the secret, in the form of catalog_name.schema_name.secret_name.

catalog_namestring: The name of the catalog where the schema and the secret reside.

schema_namestring: The name of the schema where the secret resides.

valuestring: The secret value to store. This field is input-only and is not returned in responses — use the effective_value field (via GetSecret with include_value set to true) to read the secret value. The maximum size is 60 KiB (pre-encryption). Accepted content includes passwords, tokens, keys, and other sensitive credential data.
Constraints: [ 1 .. 61440 ] characters

effective_valuestring: The secret value. Only populated in responses when you have the READ_SECRET privilege and include_value is set to true in the request. The maximum size is 60 KiB.
Constraints: [ 1 .. 61440 ] characters

expire_timestring: User-provided expiration time of the secret. This field indicates when the secret should no longer be used and may be displayed as a warning in the UI. It is purely informational and does not trigger any automatic actions or affect the secret's lifecycle.

Response

Returns the Secret object.

View as Markdown

Request

{
  "secret": {
    "name": "string",
    "owner": "string",
    "effective_owner": "string",
    "metastore_id": "string",
    "create_time": "string",
    "created_by": "string",
    "update_time": "string",
    "updated_by": "string",
    "comment": "string",
    "full_name": "string",
    "catalog_name": "string",
    "schema_name": "string",
    "value": "string",
    "effective_value": "string",
    "expire_time": "string"
  }
}

Response

{
  "name": "string",
  "owner": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "full_name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "value": "string",
  "effective_value": "string",
  "expire_time": "string"
}

Delete GA

DELETE /api/2.1/unity-catalog/secrets/{full_name}

Deletes a secret by its three-level (fully qualified) name.

You must be the owner of the secret or a metastore admin.

API scopes: unity-catalog

Parameters

full_namestringpath: The three-level (fully qualified) name of the secret (for example, catalog_name.schema_name.secret_name).

Secret object​

Get GA​

Parameters​

Response​

List GA​

Parameters​

Response​

Create GA​

Request body​

Response​

Update GA​

Parameters​

Request body​

Response​

Delete GA​

Parameters​

Secret object

Get GA

Parameters

Response

List GA

Parameters

Response

Create GA

Request body

Response

Update GA

Parameters

Request body

Response

Delete GA

Parameters