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 Signatures¶

The following method signatures are used for granting or denying the access to file or directory for a user, user role, all users, and all user roles

public void GrantForUser( String userId, String fileOrDirURL )
public void GrantForUser( String userId, String fileOrDirURL, AsyncCallback<Object> responder )
public void DenyForUser( String userId, String fileOrDirURL )
public void DenyForUser( String userId, String fileOrDirURL, AsyncCallback<Object> responder )
public void GrantForRole( String roleName, String fileOrDirURL )
public void GrantForRole( String roleName, String fileOrDirURL, AsyncCallback<Object> responder )
public void DenyForRole( String roleName, String fileOrDirURL )
public void DenyForRole( String roleName, String fileOrDirURL, AsyncCallback<Object> responder )
public void GrantForAllUsers( String fileOrDirURL )
public void GrantForAllUsers( String fileOrDirURL, AsyncCallback<Object> responder )
public void DenyForAllUsers( String fileOrDirURL )
public void DenyForAllUsers( String fileOrDirURL, AsyncCallback<Object> responder )
public void GrantForAllRoles( String fileOrDirURL )
public void GrantForAllRoles( String fileOrDirURL, AsyncCallback<Object> responder )
public void DenyForAllRoles( String fileOrDirURL )
public void DenyForAllRoles( String fileOrDirURL, AsyncCallback<Object> responder )

Use these methods to retrieve, upload, and remove a file

FilePermission.READ.<method>to set permission to load/retrieve a file
FilePermission.WRITE.<method>to set permission to upload a file
FilePermission.DELETE.<method> to set permission to remove a file
FilePermission.PERMISSION.<method> to change permissions for a file or directory

To grant access for a user¶

FilePermission.READ.GrantForUser( userId, fileOrDirURL );
FilePermission.WRITE.GrantForUser( userId, fileOrDirURL );
FilePermission.DELETE.GrantForUser( userId, fileOrDirURL );

where:

userId - ID of a user, for which you want to grant the read, write, or delete permission.
fileOrDirURL - path to a file or directory, for which you want to specify the permission.

To grant access for a user role¶

FilePermission.READ.GrantForRole( roleName, fileOrDirURL );
FilePermission.WRITE.GrantForRole( roleName, fileOrDirURL );
FilePermission.DELETE.GrantForRole( roleName, fileOrDirURL );

where:

Argument	Description
`roleName`	name of the user role, for which you want to grant the read, write, or delete permission.

fileOrDirURL - path to a file or directory, for which you want to specify the permission.

To grant access for all users¶

FilePermission.READ.GrantForAllUsers( fileOrDirURL );
FilePermission.WRITE.GrantForAllUsers( fileOrDirURL );
FilePermission.DELETE.GrantForAllUsers( fileOrDirURL );

where:

fileOrDirURL - path to a file or directory, for which you want to specify the permission.

To grant access for all user roles¶

FilePermission.READ.GrantForAllRoles( fileOrDirURL );
FilePermission.WRITE.GrantForAllRoles( fileOrDirURL );
FilePermission.DELETE.GrantForAllRoles( fileOrDirURL );

where:

fileOrDirURL - path to a file or directory, for which you want to specify the permission.

To deny access for a user¶

FilePermission.READ.DenyForUser( userId, fileOrDirURL );
FilePermission.WRITE.DenyForUser( userId, fileOrDirURL );
FilePermission.DELETE.DenyForUser( userId, fileOrDirURL );

where:

userId - ID of a user, for which you want to deny the read, write, or delete permission.
fileOrDirURL - path to a file or directory, for which you want to specify the permission.

To deny access for a user role¶

FilePermission.READ.DenyForRole( roleName, fileOrDirURL );
FilePermission.WRITE.DenyForRole( roleName, fileOrDirURL );
FilePermission.DELETE.DenyForRole( roleName, fileOrDirURL );

where:

Argument	Description
`roleName`	name of the user role, for which you want to deny the read, write, or delete permission.

fileOrDirURL - path to a file or directory, for which you want to specify the permission.

To deny access for all users¶

FilePermission.READ.DenyForAllUsers( fileOrDirURL );
FilePermission.WRITE.DenyForAllUsers( fileOrDirURL );
FilePermission.DELETE.DenyForAllUsers( fileOrDirURL );

where:

fileOrDirURL - path to a file or directory, for which you want to specify the permission.

To deny access for all user roles¶

FilePermission.READ.DenyForAllRoles( fileOrDirURL );
FilePermission.WRITE.DenyForAllRoles( fileOrDirURL );
FilePermission.DELETE.DenyForAllRoles( fileOrDirURL );

where:

fileOrDirURL - path to a file or directory, for which you want to specify the permission.

Codeless Reference¶

Set Permissions For A User/Role

files_api_permissions_set_for_user_and_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.

files_permissions_set_for_a_user_2

files_permissions_for_a_role_4

Set Permissions For All Users/Roles

files_api_permissions_set_for_all_users_and_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.

files_permissions_set_for_all_users_2

files_permissions_set_for_all_roles_4