Skip to content

Permissions API

Every data object in Backendless has its own access control list (ACL) - a matrix of operations and principals (application's users or roles). An intersection of an operation and a principal contains a permission which determines whether the principal has the right to execute the operation. These permission could be either grant or deny.

Backendless console provides an easy to understand way to see and manage these permissions. For example, the screenshot below demonstrates an ACL matrix for an object. Notice the intersection of a column for the Create operation and the AuthenticatedUser role. The cell contains a green checkmark icon representing that the permission is granted:

permission-matrix

In addition to managing the ACL permissions with Backendless Console there is also Permissions API:

Setting Permissions For A Data Table

Method

PUT

Endpoint URL

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/data/<table-name>/permissions/<permission type>

where:

Argument                Description
<table-name> Indicate the name of the data table for which you would like to grant permissions to a specific user or role.
<permission type> Specifies the type of permission to be assigned, allowing for either GRANT or DENY options.

Request Body

The request body must contain either the <objectId> or the <role-name> value. If both are present, then the <role-name> value will be ignored.

{  
   "permission": <permission>,  
   "user":<objectId>,  
         // OR  
   "role":<role-name>  
}

where:

Argument                Description
<permission> Identifies a specific permission to grant to a user or role. Supported options: "ADD", "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to grant all permission types.
<objectId> Unique identifier of the user in the Users data table.
<role-name> Specifies the name of the role for which a permission is assigned.

Return Value

None.

Example

The example below grants the "ADD" permission for the "Person" data table to all users having the "TrialUser" role.

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/GRANT' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "role": "TrialUser"  
}'

The second example below grants the "ADD" permission for the "Person" data table to the user associated with the following objectId value: "BC019481-A543-48EB-B821-47508B68B7A1".

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/GRANT' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "user": "BC019481-A543-48EB-B821-47508B68B7A1"  
}'

Setting The Object ACL For Multiple Users

Method

PUT

Endpoint URL

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/data/<table-name>/permissions/<objectId>/bulk

where:

Argument                Description
<table-name> Indicate the name of the data table where an object used for the operation is stored.
<objectId> Unique identifier of the object for which you would like to grant permissions to specific users.

Request Body

The request body must be an array of objects representing users for which permissions must be granted.

[  
    {  
        "permission":<permission>,  
        "permissionType": <permissionOption>  
        "userId":<objectid>  
     }  
...  
]

where:

Argument                Description
<permission> Identifies a specific permission to grant to a user. Supported options: "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to grant all permission types.
<permissionOption> Specifies the type of permission to be assigned, allowing for either "GRANT" or "DENY" options.
<objectId> Unique identifier of the user in the Users data table.

Return Value

None.

Example

The example below grants the "UPDATE" permission to the user represented as the first object in the array, while for the second user it revokes the "ADD_RELATION" permission. Both permission changes are associated with the object which is stored in the "Person" data table and identified by the following objectId value "BC019481-A543-48EB-B821-47508B68B7A1".

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/CB3C9021-E08E-4DB1-AB98-CEC00F83476F/bulk' \  
--header 'Content-Type: application/json' \  
--data-raw '[  
     {  
        "permission": "UPDATE",  
        "permissionType": "GRANT",  
        "userId": "BC019481-A543-48EB-B821-47508B68B7A1"  
     },  
     {  
        "permission": "ADD_RELATION",  
        "permissionType": "DENY",  
        "userId": "D24E663B-C57A-44CD-AF64-235A7CE1212D"  
     }  
]'

Setting The Object ACL For One User

Method

PUT

Endpoint URL

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/data/<table-name>/permissions/<permission type>/<objectId>

where:

Argument                Description
<table-name> Indicate the name of the data table where an object used for the operation is stored.
<permission type> Specifies the type of permission to be assigned, allowing for either GRANT or DENY options.
<objectId> Unique identifier of the object for which you would like to grant permissions to a specific user.

Request Body

{   
   "permission": <permission>,  
   "user":<objectId>  
}

where:

Argument                Description
<permission> Identifies a specific permission to grant to a user. Supported options: "ADD", "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to grant all permission types.
<objectId> Unique identifier of the user in the Users data table.

Return Value

None.

Example

The example below grants the "ADD" permission to the user identified by the following objectId value "BC019481-A543-48EB-B821-47508B68B7A1".

The permission changes are associated with the object which is stored in the "Person" data table and identified by the following objectId value "CB3C9021-E08E-4DB1-AB98-CEC00F83476F".

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/GRANT/CB3C9021-E08E-4DB1-AB98-CEC00F83476F' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "user": "BC019481-A543-48EB-B821-47508B68B7A1"  
}'

Setting The Object ACL For All Users/Roles

Method

PUT

Endpoint URL

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/data/<table-name>/permissions/<permission type>/<objectId>

where:

Argument                Description
<table-name> Indicate the name of the data table where an object used for the operation is stored.
<permission type> Specifies the type of permission to be assigned, allowing for either GRANT or DENY options.
<objectId> Unique identifier of the object for which you would like to grant permissions to all users/roles.

Request Body

{   
   "permission": <permission>,  
   "user":<objectId>,  
    // OR  
   "role":<role-name>  
}

where:

Argument                Description
<permission> Identifies a specific permission to grant to a user. Supported options: "ADD", "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to grant all permission types.
<objectId> Unique identifier of the user in the Users data table.
<role-name> Specifies the name of the role for which a permission is assigned.

Return Value

None.

Example

Grant permissions to all users for an object

In the example below, the "ADD" permission is granted to all users for an object stored in the "Person" data table. Note that to grant permission to all users, you must set the asterisk symbol in the "user" property.

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/GRANT/CB3C9021-E08E-4DB1-AB98-CEC00F83476F' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "user": "*"  
}'

Grant permissions to all roles for an object

In the example below, the "ADD" permission is granted to all roles for an object stored in the "Person" data table. Note that to grant permission to all roles, you must set the asterisk symbol in the "role" property.

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/GRANT/CB3C9021-E08E-4DB1-AB98-CEC00F83476F' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "role": "*"  
}'

Examples

To grant access for a user

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/GRANT/CB3C9021-E08E-4DB1-AB98-CEC00F83476F' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "user": "BC019481-A543-48EB-B821-47508B68B7A1"  
}'

where:

Argument                Description
permission Identifies a specific permission to grant to a user. Supported options: "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to grant all permission types.
user A user ID, for which you want to grant a permission.

Codeless Reference

data_permissions_api_1

where:

Argument                Description
GRANT/DENY Specifies whether the permission must be granted or revoked.
FIND/REMOVE/UPDATE Identifies the permission type to grant to a user.
data object A data object for which you want to grant the permission.
user id A user ID, for which you want to grant the permission.
return result When this checkbox is selected, the operation returns an empty string value.
objectId Required property. Represents the unique identifier of the object in the data table.
__class Required property. Represents the name of the data table where the operation takes place.

To grant access for a user role

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/GRANT' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "role": "TrialUser"  
}'

where:

Argument                Description
permission Identifies a specific permission to grant to a user. Supported options: "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to grant all permission types.
role A role name, for which you want to grant a permission.

Codeless Reference

data_permissions_api_2

where:

Argument                Description
GRANT/DENY Specifies whether the permission must be granted or revoked.
FIND/REMOVE/UPDATE Identifies the permission type to grant to a role.
data object A data object for which you want to grant the permission.
role name A role name, for which you want to grant a permission.
return result When this checkbox is selected, the operation returns an empty string value.
objectId Required property. Represents the unique identifier of the object in the data table.
__class Required property. Represents the name of the data table where the operation takes place.

To grant access for all users

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/GRANT/CB3C9021-E08E-4DB1-AB98-CEC00F83476F' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "user": "*"  
}'

where:

Argument                Description
permission Identifies a specific permission to grant to all users. Supported options: "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to grant all permission types.
user Must be an asterisk sign to grant a permission to all users.

Codeless Reference

data_permissions_api_3

where:

Argument                Description
GRANT/DENY Specifies whether the permission must be granted or revoked.
FIND/REMOVE/UPDATE Identifies the permission type to grant to all users.
data object A data object for which you want to grant the permission.
return result When this checkbox is selected, the operation returns an empty string value.
objectId Required property. Represents the unique identifier of the object in the data table.
__class Required property. Represents the name of the data table where the operation takes place.

To grant access for all roles

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/GRANT/CB3C9021-E08E-4DB1-AB98-CEC00F83476F' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "role": "*"  
}'

where:

Argument                Description
permission Identifies a specific permission to grant to all roles. Supported options: "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to grant all permission types.
role Must be an asterisk sign to grant a permission to all roles.

Codeless Reference

data_permissions_api_4

where:

Argument                Description
GRANT/DENY Specifies whether the permission must be granted or revoked.
FIND/REMOVE/UPDATE Identifies the permission type to grant to all roles.
data object A data object for which you want to grant the permission.
return result When this checkbox is selected, the operation returns an empty string value.
objectId Required property. Represents the unique identifier of the object in the data table.
__class Required property. Represents the name of the data table where the operation takes place.

To deny access for a user

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/DENY/CB3C9021-E08E-4DB1-AB98-CEC00F83476F' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "user": "BC019481-A543-48EB-B821-47508B68B7A1"  
}'

where:

Argument                Description
permission Identifies a specific permission to revoke from a user. Supported options: "ADD", "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to revoke all permission types.
user A user ID, for which you want to revoke a permission.

Codeless Reference

data_permissions_api_5

where:

Argument                Description
GRANT/DENY Specifies whether the permission must be granted or revoked.
FIND/REMOVE/UPDATE Identifies the permission type to revoke from a user.
data object A data object for which you want to revoke the permission.
user id A user ID, for which you want to revoke a permission.
return result When this checkbox is selected, the operation returns an empty string value.
objectId Required property. Represents the unique identifier of the object in the data table.
__class Required property. Represents the name of the data table where the operation takes place.

To deny access for a user role

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/DENY/CB3C9021-E08E-4DB1-AB98-CEC00F83476F' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "role": "TrialUser"  
}'

where:

Argument                Description
permission Identifies a specific permission to revoke from a role. Supported options: "ADD", "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to revoke all permission types.
role A role name, for which you want to revoke a permission.

Codeless Reference

data_permissions_api_6

where:

Argument                Description
GRANT/DENY Specifies whether the permission must be granted or revoked.
FIND/REMOVE/UPDATE Identifies the permission type to revoke from a role.
data object A data object for which you want to revoke the permission.
role name A role name, for which you want to revoke a permission.
return result When this checkbox is selected, the operation returns an empty string value.
objectId Required property. Represents the unique identifier of the object in the data table.
__class Required property. Represents the name of the data table where the operation takes place.

To deny access for all users

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/DENY/CB3C9021-E08E-4DB1-AB98-CEC00F83476F' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "user": "*"  
}'

where:

Argument                Description
permission Identifies a specific permission to revoke from all users. Supported options: "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to revoke all permission types.
user Must be an asterisk sign to revoke a permission from all users.

Codeless Reference

data_permissions_api_7

where:

Argument                Description
GRANT/DENY Specifies whether the permission must be granted or revoked.
FIND/REMOVE/UPDATE Identifies the permission type to revoke from all users.
data object A data object for which you want to revoke the permission.
return result When this checkbox is selected, the operation returns an empty string value.
objectId Required property. Represents the unique identifier of the object in the data table.
__class Required property. Represents the name of the data table where the operation takes place.

To deny access for all user roles

curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/permissions/DENY/CB3C9021-E08E-4DB1-AB98-CEC00F83476F' \  
--header 'Content-Type: application/json' \  
--data-raw '{  
   "permission": "ADD",  
   "role": "*"  
}'

where:

Argument                Description
permission Identifies a specific permission to revoke from all roles. Supported options: "UPDATE", "FIND", "REMOVE", "DESCRIBE", "PERMISSION", "LOAD_RELATIONS", "ADD_RELATION", "DELETE_RELATION", "UPSERT". You can also use the asterisk symbol "*" to revoke all permission types.
role Must be an asterisk sign to revoke a permission from all roles.

Codeless Reference

data_permissions_api_8

where:

Argument                Description
GRANT/DENY Specifies whether the permission must be granted or revoked.
FIND/REMOVE/UPDATE Identifies the permission type to revoke from all roles.
data object A data object for which you want to revoke the permission.
return result When this checkbox is selected, the operation returns an empty string value.
objectId Required property. Represents the unique identifier of the object in the data table.
__class Required property. Represents the name of the data table where the operation takes place.