Skip to main content

Secret Scope

View as Markdown

An organizational resource for storing secrets. Secret scopes can be different types (Databricks-managed, Azure KeyVault backed, etc), and ACLs can be applied to control permissions for all secrets within a scope.

SecretScope object​

An organizational resource for storing secrets. Secret scopes can be different types (Databricks-managed, Azure KeyVault backed, etc), 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 resource id of the azure KeyVault that user wants to associate the scope with.

dns_namestring

The DNS of the KeyVault

List​

GET /api/2.0/secrets/scopes/list

Lists all secret scopes available in the workspace.

Example response:

.. code::

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

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​

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.

Example request:

.. code::

{
    "scope": "my-simple-databricks-scope",
    "initial_manage_principal": "users"
    "scope_backend_type": "databricks|azure_keyvault",
    # below is only required if scope type is azure_keyvault
    "backend_azure_keyvault": {
        "resource_id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/xxxx/providers/Microsoft.KeyVault/vaults/xxxx",
        "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "dns_name": "https://xxxx.vault.azure.net/",
    }
}

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 a given Azure KeyVault. The caller must provide the keyvault_resource_id and the tenant_id for the key vault. If scope_backend_type is databricks or is unspecified, an empty secret scope is created and stored in <Databricks>'s own 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 normal user attempts to create a scope with name reserved for databricks internal usage. Throws UNAUTHENTICATED if unable to verify user access permission on Azure KeyVault

API scopes: secrets

Request body​

scopestring

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 the scope will be created with. If not specified, will default 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_idstring

The resource id of the azure KeyVault that user wants to associate the scope with.

dns_namestring

The DNS of the KeyVault

Delete​

POST /api/2.0/secrets/scopes/delete

Deletes a secret scope.

Example request:

.. code::

&#123;
    "scope": "my-secret-scope"
&#125;

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. Throws BAD_REQUEST if system user attempts to delete internal secret scope.

API scopes: secrets

Request body​

scopestring

Name of the scope to delete.