Secret

View as Markdown

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

GetGET /api/2.0/secrets/getListGET /api/2.0/secrets/listUpdatePOST /api/2.0/secrets/putDeletePOST /api/2.0/secrets/delete

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 last updated timestamp (in milliseconds) for the secret.

View as Markdown

The SecretMetadata object

{
  "key": "string",
  "last_updated_timestamp": 0
}

Get GA

GET /api/2.0/secrets/get

Gets a secret for a given key and scope. This API can only be called from the DBUtils interface. Users need the READ permission to make this call.

Example response:

.. code::

{ "key": "my-string-key", "value": <bytes of the secret value> }

Note that the secret value returned is in bytes. The interpretation of the bytes is determined by the caller in DBUtils and the type the data is decoded into.

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.

Note: This is explicitly an undocumented API. It also doesn't need to be supported for the /preview prefix, because it's not a customer-facing API (i.e. only used for DBUtils SecretUtils to fetch secrets).

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope or secret exists. Throws BAD_REQUEST if normal user calls get secret outside of a notebook. AKV specific errors: Throws INVALID_PARAMETER_VALUE if secret name is not alphanumeric or too long. Throws PERMISSION_DENIED if secret manager cannot access AKV with 403 error Throws MALFORMED_REQUEST if secret manager cannot access AKV with any other 4xx error

API scopes: secrets

Parameters

scopestringquery

The name of the scope that contains the secret.

keystringquery

Name of the secret to fetch value information.

Response

keystring

A unique name to identify the secret.

valuestring

The value of the secret in its byte representation.

View as Markdown

Response

{
  "key": "string",
  "value": "string"
}

List 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.

Example response:

.. code::

{
    "secrets": [
        {
            "key": "my-string-key"",
            "last_updated_timestamp": "1520467595000"
        },
        {
            "key": "my-byte-key",
            "last_updated_timestamp": "1520467595000"
        },
    ]
}

The lastUpdatedTimestamp returned is in milliseconds since epoch.

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

scopestringquery

The name of the scope to list secrets within.

Response

Returns a list of SecretMetadata objects.

View as Markdown

Response

{
  "secrets": [
    {
      "key": "string",
      "last_updated_timestamp": 0
    }
  ]
}

Update 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.

Example request:

.. code::

{
    "scope": "my-databricks-scope",
    "key": "my-string-key",
    "string_value": "foobar"
}

The input fields "string_value" or "bytes_value" specify the type of the secret, which will determine the value returned when the secret value is requested. Exactly one must be specified.

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

scopestring

The name of the scope to which the secret will be associated with.

keystring

A unique name to identify the secret.

string_valuestringRequired

If specified, note that the value will be stored in UTF-8 (MB4) form.

bytes_valuestringRequired

If specified, value will be stored as bytes.

View as Markdown

Request

{
  "scope": "string",
  "key": "string",
  "string_value": "string",
  "bytes_value": "string"
}

Response

{}

Delete 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.

Example request:

.. code::

{
    "scope": "my-secret-scope",
    "key": "my-secret-key"
}

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 system user attempts to delete an internal secret, or request is made against Azure KeyVault backed scope.

API scopes: secrets

Request body

scopestring

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

keystring

Name of the secret to delete.

View as Markdown

Request

{
  "scope": "string",
  "key": "string"
}

Response

{}