Skip to main content

Secret Acl

View as Markdown

An item representing an ACL rule applied to the given principal (user or group) on the associated scope point.

AclItem object​

An item representing an ACL rule applied to the given principal (user or group) on the associated scope point.

principalstring

The principal in which the permission is applied.

permissionstring

The permission level applied to the principal.

Values: READ, WRITE, MANAGE

Get​

GET /api/2.0/secrets/acls/get

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

Users must have the MANAGE permission to invoke this API.

Example response:

.. code::

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

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. Throws INVALID_PARAMETER_VALUE if the permission or principal is invalid.

API scopes: secrets

Parameters​

scopestringquery

The name of the scope to fetch ACL information from.

principalstringquery

The principal to fetch ACL information for.

Response​

Returns the AclItem object.

List​

GET /api/2.0/secrets/acls/list

Lists the ACLs set on the given scope.

Users must have the MANAGE permission to invoke this API.

Example response:

.. code::

{
    "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 the user does not have permission to make this API call.

API scopes: secrets

Parameters​

scopestringquery

The name of the scope to fetch ACL information from.

Response​

Returns a list of AclItem objects.

Create​

POST /api/2.0/secrets/acls/put

Creates or overwrites 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.

Note that in general, secret values can only be read from within a command on a cluster (for example, through a notebook). There is no API to read the actual secret value material outside of a cluster. However, the user's permission will be applied based on who is executing the command, and they must have at least READ permission.

Users must have the MANAGE permission to invoke this API.

Example request:

.. code::

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

API scopes: secrets

Request body​

scopestring

The name of the scope to apply permissions to.

principalstring

The principal in which the permission is applied.

permissionstring

The permission level applied to the principal.

Values: READ, WRITE, MANAGE

Delete​

POST /api/2.0/secrets/acls/delete

Deletes the given ACL on the given scope.

Users must have the MANAGE permission to invoke this API.

Example request:

.. code::

&#123;
    "scope": "my-secret-scope",
    "principal": "data-scientists"
&#125;

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope, principal, or ACL exists. Throws PERMISSION_DENIED if the user does not have permission to make this API call. Throws INVALID_PARAMETER_VALUE if the permission or principal is invalid.

API scopes: secrets

Request body​

scopestring

The name of the scope to remove permissions from.

principalstring

The principal to remove an existing ACL from.