Secrets API

Create Secret Scope

Create a new secret scope.

The scope name must consist of alphanumeric characters, dashes, underscores, and periods, and may not exceed 128 characters. The maximum number of scopes in a workspace is 100.

Example request:

{
  "scope": "my-simple-databricks-scope",
  "initial_manage_principal": "users"
}

If initial_manage_principal is specified, the initial ACL applied to the scope is applied to the supplied principal (user or group) with MANAGE permissions. The only supported principal for this option is the group users, which contains all users in the workspace. If initial_manage_principal is not specified, the initial ACL with MANAGE permission applied to the scope is assigned to the API request issuer’s user identity.

Throws RESOURCE_ALREADY_EXISTS if a scope with the given name already exists. Throws RESOURCE_LIMIT_EXCEEDED if maximum number of scopes in the workspace is exceeded. Throws INVALID_PARAMETER_VALUE if the scope name is invalid.

Delete Secret Scope

Delete a secret scope.

Example request:

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

Throws RESOURCE_DOES_NOT_EXIST if the scope does not exist. Throws PERMISSION_DENIED if the user does not have permission to make this API call.

List Secret Scopes

List all secret scopes available in the workspace.

Example response:

{
  "scopes": [{
      "name": "my-databricks-scope",
      "backend_type": "DATABRICKS"
  },{
      "name": "mount-points",
      "backend_type": "DATABRICKS"
  }]
}

Throws PERMISSION_DENIED if you do not have permission to make this API call.

Put Secret

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

You can read a secret value only from within a command on a cluster (for example, through a notebook); there is no API to read a secret value outside of a cluster. The permission applied is based on who is invoking the command and you must have at least READ permission.

Example request:

{
  "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 key name or value length is invalid. Throws PERMISSION_DENIED if the user does not have permission to make this API call.

Delete Secret

Delete the secret stored in this secret scope. You must have WRITE or MANAGE permission on the secret scope.

Example request:

{
  "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 you do not have permission to make this API call.

List Secrets

List the secret keys that are stored at this scope. This is a metadata-only operation; you cannot retrieve secret data using this API. You must have READ permission to make this call.

Example response:

{
  "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 you do not have permission to make this API call.

Put Secret ACL

Create or overwrite the ACL associated with the given principal (user or group) on the specified scope point. In general, a user or group will use the most powerful permission available to them, and permissions are ordered as follows:

• MANAGE - Allowed to change ACLs, and read and write to this secret scope.
• WRITE - Allowed to read and write to this secret scope.
• READ - Allowed to read this secret scope and list what secrets are available.

You must have the MANAGE permission to invoke this API.

Example request:

{
  "scope": "my-secret-scope",
  "principal": "data-scientists",
  "permission": "READ"
}

The principal is a user or group name corresponding to an existing Databricks principal to be granted or revoked access.

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope exists. Throws RESOURCE_ALREADY_EXISTS if a permission for the principal already exists. Throws INVALID_PARAMETER_VALUE if the permission is invalid. Throws PERMISSION_DENIED if you do not have permission to make this API call.

Delete Secret ACL

Delete the given ACL on the given scope.

You must have the MANAGE permission to invoke this API.

Example request:

{
  "scope": "my-secret-scope",
  "principal": "data-scientists"
}

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope, principal, or ACL exists. Throws PERMISSION_DENIED if you do not have permission to make this API call.

Get Secret ACL

Describe the details about the given ACL, such as the group and permission.

You must have the MANAGE permission to invoke this API.

Example response:

{
  "principal": "data-scientists",
  "permission": "READ"
}

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope exists. Throws PERMISSION_DENIED if you do not have permission to make this API call.

List Secret ACLs

List the ACLs set on the given scope.

You must have the MANAGE permission to invoke this API.

Example response:

{
  "acls": [
    {
        "principal": "admins",
        "permission": "MANAGE"
    },{
        "principal": "data-scientists",
        "permission": "READ"
    }
  ]
}

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope exists. Throws PERMISSION_DENIED if you do not have permission to make this API call.

Data Structures