Permissions API

Backendless security mechanism assigns an Access Control List (ACL) to every file in the file storage. An ACL defines users and user roles that have permissions to read, write, or delete a file. The Permissions API allows programmatic control over file ACL by granting or denying permissions to a file for a user or a user role. Using the API permissions can be applies for a user or user role individually or in "bulk" - for all users or user roles in a single call.

The path or the url argument in the APIs below must identify a file or directory for which the permission is modified. The value must be the short version of the path. For example, suppose the full URL of a file in the file storage system is:

https://backendlessappcontent.com/31CB9FED-F34C-5541-FF26-6C2B6719F200/23432-A6B2-FF6B-31CB9FED/files/movies/vacation.mp4

The path to the file in the API call must contain only the directory and the file name (without the leading slash):

movies/vacation.mp4

The user account (or the role) on which behalf the API is executed must contain the Permission permission. For example, if the call is made by an authenticated user, the role for the user account would be AuthenticatedUser. The role must have the Permission permission in order for the API call to go through.

Method

PUT

Endpoint URI

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

https://xxxx.backendless.app/api/files/permissions/<permission type>/<path>/<file_name>

where:

Argument	Description
<permission type>	type of the permission, that is grant or deny.
<path>	path to a file, for which you want to specify the permission.

Sample Request Body:

To set permissions for a user

{  
    "permission": "READ" | "DELETE" | "WRITE",  
    "user": userid  
}

To set permissions for all users, specify "*" value for the user argument.

To set permissions for a user role

{  
    "permission": "READ" | "DELETE" | "WRITE",  
    "role": rolename  
}

To set permissions for all user roles, specify "*" value for the role argument.

Sample Response Body

void or error

Codeless Reference

Set Permissions For A User/Role

where:

Argument	Description
GRANT/DENY	Specify if you want to grant or deny specific permissions.
READ, WRITE, DELETE	Select the permission type that you want to grant.
path	Path to a file or directory, for which you want to specify the permission.
user id	Unique identifier of the user, which is also known as the objectId. The value of the objectId property is stored in the Users data table.
role name	The name of the role that must be granted permissions.
return result	When this box is checked, the operation returns an object containing permission details.

Returns an object containing the "permissions" and the "role" properties. The former identifies the permission type such as READ, WRITE, DELETE and the latter identifies the role which was assigned these permissions.

The examples below grant permissions to READ the "/misc" folder to the user with the user id``"20FFE530-124A-4ABC-9059-3DD6F7F605F5" / to a "Trial User" role.

Set Permissions For All Users/Roles

where:

Argument	Description
GRANT/DENY	Specify if you want to grant or deny specific permissions.
READ, WRITE, DELETE	Select the permission type that you want to grant.
return result	When this box is checked, the operation returns an object containing permission details.

Returns an object containing the "permissions" and the "role" properties. The former identifies the permission type such as READ, WRITE, DELETE and the latter identifies the role which was assigned these permissions.

The examples below grant permissions to READ the "/misc" folder to all users/roles.