SharePoint Online REST APIs (Part VI): Permissions
In the SharePoint Online REST APIs series, I’ll be sharing the most common APIs I use. I mainly use these APIs in Power Automate, so I’ll base the information in this series on the data you need for a Send an HTTP request to SharePoint action.
This article explores how to break and grant permissions to users and SharePoint Online groups. This is not a comprehensive list; rather a list of calls that I use when I can’t use predefined Power Automate actions. I have used the color red to identify interchangeable values.
Check if a subsite has unique permissions
Method
URI
GET
_api/web?$select=HasUniqueRoleAssignments
This call checks to see if a site is inheriting from its parents, or has broken inheritance. This call can also work on lists, libraries, folders and items (see below).
Check if an item has unique permissions
Method
URI
GET
_api/web/lists(guid'GUID')/items(40)?$select=HasUniqueRoleAssignments
As mentioned above, this call checks to see if a specific item has unique permissions. In this example, I am looking at an item in a specific library that has an ID of 40.
Break permission inheritance on an item
Method
URI
POST
_api/web/lists/GetByTitle('Site Pages')/items(5)/BreakRoleInheritance(CopyRoleAssignments=true, ClearSubscopes=true)
This example breaks inheritance on a site page. However, you can also use this call to break permission inheritance on a site, list, library or item. BreakRoleInheritance essentially breaks the inheritance. The CopyRoleAssignments and ClearSubscopes are parameters which can be true or false. For more information on these parameters, read this article.
Get user principal ID
Method
URI
GET
_api/web/SiteUsers/GetByEmail('name@email.com')/Id
After you’ve broken inheritance, you need to add users (or groups; which is explored next). Before you can add a user to an item/site/list etc., you’ll need to get their Id.
Get group principal ID
Method
URI
GET
_api/web/SiteGroups/GetByName('Site Name Owners')?$select=Id
This is the same concept as above, however, it is getting the Id of a SharePoint group.
Give permissions to a user or group
Method
URI
POST
_api/web/lists/GetByTitle('Site Pages')/items(5)/RoleAssignments/AddRoleAssignment(PrincipalId=9,RoleDefId=1073741827)
Finally, we can grant permissions to a user or group. To do this, we need the principal Id (which we got in the above calls) and the value for RoleDefId. These values are not straight forward. I have included the main permissions in the table below, but Microsoft details some more on their site.
| Permission Level | RoleDefId Value |
|---|---|
| Full Control | 1073741829 |
| Contribute | 1073741827 |
| Read | 1073741826 |
Hi.
Unfortunately, my groupID and userID are the same (yes, the same integer number).
How can I grant permissions to a library item only with user email address?
Hi ,
I want create a sharing link of SharePoint documents for external users using REST API with PHP.Could me help me out how I can achieve this. waiting for your reply.
Hi, how do I create a new user group please? That part was missing in the article. Thanks much.