Skip to main content

Secret Scope

View as Markdown

An organizational resource for storing secrets. A secret scope is either Databricks-backed or Azure Key Vault-backed, and ACLs can be applied to control permissions for all secrets within a scope.

SecretScope object​

An organizational resource for storing secrets. A secret scope is either Databricks-backed or Azure Key Vault-backed, and ACLs can be applied to control permissions for all secrets within a scope.

namestring

A unique name to identify the secret scope.

backend_typestring

The type of secret scope backend.

Values:

  • DATABRICKS
  • AZURE_KEYVAULT
keyvault_metadataobject

The metadata for the secret scope if the type is AZURE_KEYVAULT.

Show child attributesHide child attributes
resource_idstring

The Azure resource ID of the key vault to associate with the scope.

dns_namestring

The DNS name of the key vault, for example https://my-key-vault.vault.azure.net/.

List all scopes GA​

GET /api/2.0/secrets/scopes/list

Lists all secret scopes available in the workspace.

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

API scopes: secrets

Response​

Returns a list of SecretScope objects.

Create a new secret scope GA​

POST /api/2.0/secrets/scopes/create

Creates a new secret scope.

The scope name must consist of alphanumeric characters, dashes, underscores, and periods, and may not exceed 128 characters.

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.

If scope_backend_type is AZURE_KEYVAULT, a secret scope is created with secrets from an existing Azure key vault. The caller must provide the key vault's resource ID and DNS name in backend_azure_keyvault. If scope_backend_type is DATABRICKS or is unspecified, an empty secret scope is created and stored in Databricks-managed storage.

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. Throws BAD_REQUEST if request violated constraints. Throws CUSTOMER_UNAUTHORIZED if the scope name is reserved for Databricks internal use. Throws UNAUTHENTICATED if Databricks cannot verify the caller's access to the Azure key vault.

API scopes: secrets

Request body​

scopestringRequired

Scope name requested by the user. Scope names are unique.

initial_manage_principalstring

The principal that is initially granted MANAGE permission to the created scope.

scope_backend_typestring

The backend type of the new scope. Defaults to DATABRICKS.

Values:

  • DATABRICKS
  • AZURE_KEYVAULT
backend_azure_keyvaultobject

The metadata for the secret scope if the type is AZURE_KEYVAULT

Show child attributesHide child attributes
resource_idstringRequired

The Azure resource ID of the key vault to associate with the scope.

dns_namestringRequired

The DNS name of the key vault, for example https://my-key-vault.vault.azure.net/.

Delete a secret scope GA​

POST /api/2.0/secrets/scopes/delete

Deletes a 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.

API scopes: secrets

Request body​

scopestringRequired

Name of the scope to delete.