Create Permission

The Create Permission operation creates a permission (a security descriptor) at the share level. You can use the created security descriptor for the files and directories in the share. This API is available as of version 2019-02-02.

Protocol availability

Enabled file share protocol	Available
SMB
NFS

Request

You can construct the Create Permission request as shown here. We recommend that you use HTTPS.

Replace the path components shown in the request URI with your own components, as shown here:

For information about path-naming restrictions, see Name and reference shares, directories, files, and metadata.

URI parameters

You can specify additional parameters on the request URI as shown here:

Request headers

The required and optional request headers are described in the following table:

Request body

You create a security descriptor by placing a JSON object in the request body. The JSON object can have the following fields:

If using SDDL, the SDDL string format of the security descriptor shouldn't have a domain relative identifier (for example, DU, DA, or DD) in it.

{
    "permission": "<SDDL>"
}

In version 2024-11-04 or later, you can optionally explicitly specify that the permission is in SDDL format:

{
    "format": "sddl",
    "permission": "<SDDL>"
}

In version 2024-11-04 or later, you can also create a permission in base-64 encoded binary format. In that case, you must explicitly specify that the format is "binary".

{
    "format": "binary",
    "permission": "<base64>"
}

Sample request

PUT https://myaccount.file.core.windows.net/myshare?restype=share&comp=filepermission HTTP/1.1  

Request Headers:
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=

Request Body:
{"permission": "O:S-1-5-21-2127521184-1604012920-1887927527-21560751G:S-1-5-21-2127521184-1604012920-1887927527-513D:AI(A;;FA;;;SY)(A;;FA;;;BA)(A;;0x1200a9;;;S-1-5-21-397955417-626881126-188441444-3053964)"}

Response

The response includes an HTTP status code and a set of response headers.

Status code

A successful operation returns status code 201 (Created).

For information about status codes, see Status and error codes.

Response headers

The response for this operation includes the following headers. The response might also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response body

None.

Authorization

Only the account owner or a caller that has a share-level shared access signature with write and delete authorization may call this operation.

Remarks

To make the SDDL format portable across domain and non-domain joined machines, the caller can use the ConvertSecurityDescriptorToStringSecurityDescriptor Windows function to get the base SDDL string for the security descriptor. The caller can then replace the SDDL notation that's listed in the following table with the correct SID value.