Skip to main content

Secret

View as Markdown

SecretMetadata object​

The metadata about a secret. Returned when listing secrets. Does not contain the actual secret value.

keystring

A unique name to identify the secret.

last_updated_timestampint64

The time the secret was last written, in milliseconds since the Unix epoch.

Get a secret GA​

GET /api/2.0/secrets/get

Gets the bytes representation of a secret value for the specified scope and key. Users need the READ permission to make this call.

The secret value is returned as bytes regardless of whether it was written with string_value or bytes_value, so the caller decides how to decode it. Values returned by this API are not redacted.

Throws RESOURCE_DOES_NOT_EXIST if no such secret or secret scope exists. Throws PERMISSION_DENIED if the user does not have permission to make this API call. Azure Key Vault-backed scopes can also return the following errors: Throws INVALID_PARAMETER_VALUE if the secret name is not alphanumeric or is too long. Throws PERMISSION_DENIED if Databricks cannot access the key vault (HTTP 403). Throws MALFORMED_REQUEST if Databricks cannot access the key vault with any other 4xx error.

API scopes: secrets

Parameters​

scopestringRequiredquery

The name of the scope that contains the secret.

keystringRequiredquery

Name of the secret to fetch value information.

Response​

keystring

A unique name to identify the secret.

valuestring

The secret value, base64-encoded. A secret written with string_value is returned as the base64 encoding of its UTF-8 bytes.

List secret keys GA​

GET /api/2.0/secrets/list

Lists the secret keys that are stored at this scope. This is a metadata-only operation; secret data cannot be retrieved using this API. Users need the READ permission to make this call.

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope exists. Throws PERMISSION_DENIED if the user does not have permission to make this API call.

API scopes: secrets

Parameters​

scopestringRequiredquery

The name of the scope to list secrets within.

Response​

Returns a list of SecretMetadata objects.

Add a secret GA​

POST /api/2.0/secrets/put

Inserts a secret under the provided scope with the given name. If a secret already exists with the same name, this command overwrites the existing secret's value. The server encrypts the secret using the secret scope's encryption settings before storing it. You must have WRITE or MANAGE permission on the secret scope.

The secret key must consist of alphanumeric characters, dashes, underscores, and periods, and cannot exceed 128 characters. The maximum allowed secret value size is 128 KB. The maximum number of secrets in a given scope is 1000.

Exactly one of string_value or bytes_value must be specified. The server stores both kinds of value as bytes and does not record which one was used.

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope exists. Throws RESOURCE_LIMIT_EXCEEDED if maximum number of secrets in scope is exceeded. Throws INVALID_PARAMETER_VALUE if the request parameters are invalid. Throws PERMISSION_DENIED if the user does not have permission to make this API call. Throws MALFORMED_REQUEST if request is incorrectly formatted or conflicting. Throws BAD_REQUEST if request is made against Azure KeyVault backed scope.

API scopes: secrets

Request body​

scopestringRequired

The name of the scope to store the secret in.

keystringRequired

A unique name to identify the secret.

string_valuestring

The secret value as text. The server stores it as the UTF-8 encoding of the string.

bytes_valuestring

The secret value as raw bytes. The bytes must be base64-encoded in the JSON request body.

Delete a secret GA​

POST /api/2.0/secrets/delete

Deletes the secret stored in this secret scope. You must have WRITE or MANAGE permission on the Secret Scope.

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope or secret exists. Throws PERMISSION_DENIED if the user does not have permission to make this API call. Throws BAD_REQUEST if the request is made against an Azure Key Vault-backed scope.

API scopes: secrets

Request body​

scopestringRequired

The name of the scope that contains the secret to delete.

keystringRequired

Name of the secret to delete.