Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Specifying Item-Level Permissions

Specifying Item-Level Permissions

The Backend Services RESTful API allows you to update item-level permissions from any application that can make HTTP calls. When specifying item-level permissions you are manipulating the item's ACL. This can be done only by the item owner or using Master Key authorization.

You have these options to specify item-level permissions:

Setting Item-Level Permissions

The set operation substitutes an entire ACL entry of a content type item or creates a new ACL entry in case it doesn't exist.

The set operation is potentially destructive. Use it with care.

The next example sets the UsersCanUpdate array to an array containing a single user ID and also sets the EveryoneCanRead policy to false. For the full set of fields that you can set, see List of Item-Level Permissions.

var acl = {
    EveryoneCanRead: false,
    UsersCanUpdate: [ "8c374b80-c198-11e2-bdc8-85b57a2c1347" ]
};
$.ajax({
    type: "PUT",
    url: 'https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl',
    headers: { "Authorization" : "Masterkey your-master-key" },
    contentType: "application/json",
    data: JSON.stringify(acl),
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});
Request:
    PUT https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl 
Headers:
    Authorization  MasterKey your-master-key
    Content-Type application/json 
Payload - raw:
    {
        "EveryoneCanRead": false,
        "UsersCanUpdate": [ "8c374b80-c198-11e2-bdc8-85b57a2c1347" ]
    } 
Response:
    Status: 200 OK
    Content-Type: application/json

On successful operation, you get this result:

STATUS 200 OK
{
    "Result": 1
}

An alternative syntax allows using the $set modifier:

var acl = $set: {
    EveryoneCanRead: false,
    UsersCanUpdate: [ "8c374b80-c198-11e2-bdc8-85b57a2c1347" ]
};
$.ajax({
    type: "PUT",
    url: 'https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl',
    headers: { "Authorization" : "Masterkey your-master-key" },
    contentType: "application/json",
    data: JSON.stringify(acl),
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});
Request:
    PUT https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl 
Headers:
    Authorization  MasterKey your-master-key
    Content-Type application/json 
Payload - raw:
    {
        "$set": {
            "EveryoneCanRead": false,
            "UsersCanUpdate": [ "8c374b80-c198-11e2-bdc8-85b57a2c1347" ]
        }
    } 
Response:
    Status: 200 OK
    Content-Type: application/json

Unsetting Item-Level Permissions

The unset operation deletes one or more ACL entries from a content type item.

The next example deletes the entire UsersCanUpdate ACL entry. For the full set of fields that you can unset, see List of Item-Level Permissions.

var acl = $unset: {
    UsersCanUpdate: ""
};
$.ajax({
    type: "PUT",
    url: 'https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl',
    headers: { "Authorization" : "Masterkey your-master-key" },
    contentType: "application/json",
    data: JSON.stringify(acl),
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});
Request:
    PUT https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl 
Headers:
    Authorization  MasterKey your-master-key
    Content-Type application/json 
Payload - raw:
    {
        "$unset": {
            "UsersCanUpdate": ""
        }
    } 
Response:
    Status: 200 OK
    Content-Type: application/json

On successful operation, you get this result:

STATUS 200 OK
{
    "Result": 1
}

You can also unset multiple ACL entries:

var acl = $unset: {
    EveryoneCanRead: "",
    UsersCanUpdate: ""
};
{
    "$unset": {
        "EveryoneCanRead": "",
        "UsersCanUpdate": ""
    }
}

Updating Item-Level Permissions

When you need to only add or remove entries from the content type item's ACL, use the update operation.

The update options include:

Adding a Single ID to an Array

You can add a single user or role ID to the various ACL arrays using the $push modifier.

The next example adds a single user ID to the UsersCanUpdate array:

var acl = {
    $push: {
        UsersCanUpdate: "8c374b80-c198-11e2-bdc8-85b57a2c1347"
    }
};
$.ajax({
    type: "PUT",
    url: 'https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl',
    headers: { "Authorization" : "Masterkey your-master-key" },
    contentType: "application/json",
    data: JSON.stringify(acl),
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});
Request:
    PUT https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl 
Headers:
    Authorization  MasterKey your-master-key
    Content-Type application/json 
Payload - raw:
    {
        "$push": {
            "UsersCanUpdate": "8c374b80-c198-11e2-bdc8-85b57a2c1347"
        }
    } 
Response:
    Status: 200 OK
    Content-Type: application/json

On successful operation, you get this result:

STATUS 200 OK
{
    "Result": 1
}

Adding Multiple IDs to an Array

You can add multiple user or role IDs to the various ACL arrays using the $pushAll modifier.

The next example adds a pair of user IDs to the UsersCanUpdate array:

var acl = {
    $pushAll: {
        UsersCanUpdate: [ "8c374b80-c198-11e2-bdc8-85b57a2c1347", "8c374b80-c198-11e2-bdc8-85b57a2c1349" ]
    }
};
$.ajax({
    type: "PUT",
    url: 'https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl',
    headers: { "Authorization" : "MasterKey your-master-key" },
    contentType: "application/json",
    data: JSON.stringify(acl),
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});
Request:
    PUT https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl 
Headers:
    Authorization  MasterKey your-master-key
    Content-Type application/json 
Payload - raw:
    {
        "$pushAll": {
            "UsersCanUpdate": [ "8c374b80-c198-11e2-bdc8-85b57a2c1347", "8c374b80-c198-11e2-bdc8-85b57a2c1349" ]
        }
    } 
Response:
    Status: 200 OK
    Content-Type: application/json

On successful operation, you get this result:

STATUS 200 OK
{
    "Result": 1
}

Removing a Single Entry from an Array

You can remove a single user or role ID from the various ACL arrays using the $pull modifier.

The next example removes a single user ID from the UsersCanUpdate array:

var acl = {
    $pull: {
        UsersCanUpdate: "8c374b80-c198-11e2-bdc8-85b57a2c1347"
    }
};
$.ajax({
    type: "PUT",
    url: 'https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl',
    headers: { "Authorization" : "MasterKey your-master-key" },
    contentType: "application/json",
    data: JSON.stringify(acl),
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});
Request:
    PUT https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl 
Headers:
    Authorization  MasterKey your-master-key
    Content-Type application/json 
Payload - raw:
    {
        "$pull": {
            "UsersCanUpdate": "8c374b80-c198-11e2-bdc8-85b57a2c1347"
        }
    } 
Response:
    Status: 200 OK
    Content-Type: application/json

On successful operation, you get this result:

STATUS 200 OK
{
    "Result": 1
}

Removing Multiple Entries from an Array

You can remove multiple user or role IDs from the various ACL arrays using the $pullAll modifier.

The next example removes a pair of user IDs from the UsersCanUpdate array:

var acl = {
    $pullAll: {
        UsersCanUpdate: [ "8c374b80-c198-11e2-bdc8-85b57a2c1347", "8c374b80-c198-11e2-bdc8-85b57a2c1349" ]
    }
};
$.ajax({
    type: "PUT",
    url: 'https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl',
    headers: { "Authorization" : "MasterKey your-master-key" },
    contentType: "application/json",
    data: JSON.stringify(acl),
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});
Request:
    PUT https://api.everlive.com/v1/your-app-id/type-name/item-id/_acl 
Headers:
    Authorization  MasterKey your-master-key
    Content-Type application/json 
Payload - raw:
    {
        "$pullAll": {
            "UsersCanUpdate": [ "8c374b80-c198-11e2-bdc8-85b57a2c1347", "8c374b80-c198-11e2-bdc8-85b57a2c1349" ]
        }
    } 
Response:
    Status: 200 OK
    Content-Type: application/json

On successful operation, you get this result:

STATUS 200 OK
{
    "Result": 1
}

See Also

Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.