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:
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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. |