# Create

Launch stage: GA

`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

- `scope` (string, optional)
  The name of the scope to apply permissions to.
- `principal` (string, optional)
  The principal in which the permission is applied.
- `permission` (string, optional)
  The permission level applied to the principal.
  Possible values: `READ`, `WRITE`, `MANAGE`

## Response

```json
{}
```