Semantic model REST API permissions
This article describes Power BI permissions in general, and semantic model permissions in the context of the Power BI REST APIs.
Power BI permissions
Power BI has two sets of permissions:
Workspace permissions
Workspace permissions, also known as folder permissions or roles, are the highest level of permissions in Power BI. These permissions override permissions that are given to a specific item in the workspace folder.
The table below lists the four types of folder roles. It shows each role's level, and the code string returned by the Power BI REST APIs. Admin is the highest workspace permission level, and viewer is the lowest. Every permission level includes the capabilities of the permissions below it. You can review the capabilities of each permission in Workspace roles.
| Folder Role | Level | Derived permissions for semantic models created in the workspace |
|---|---|---|
| Admin | 4 | ReadWriteReshareExplore |
| Member | 3 | ReadWriteReshareExplore |
| Contributor | 2 | ReadWriteExplore |
| Viewer | 1 | Read |
Note
The write permission is applied to Power BI semantic models created by admin, member and contributor users in a workspace they own. The write permission can be granted or deleted using workspace permissions only. It cannot directly be granted to, or deleted from, a Power BI item.
Get and add workspace permissions with APIs
To get and add workspace permissions programmatically, use these APIs:
Groups - Add Group User - A POST API for adding workspace permissions
Groups - Update Group User - A PUT API for changing workspace permissions
Groups - Get Group Users - A GET API for getting workspace permissions
Item permissions
Power BI items, such as reports, semantic models, and dashboards have their own permissions. Item permissions can't override workspace permissions, and can only be granted by someone who has at least the same level of permission.
Semantic model permissions and REST APIs
Semantic model permissions are part of the item permissions. The table below lists the Power BI semantic model permissions and their representation in the Power BI REST APIs.
Tip
Although the API permissions are identical to the Power BI service permissions, build permissions are referred to as explore permissions in the APIs.
| Permission | Read | Explore | Reshare |
|---|---|---|---|
| Description | Allows the user to read the content of the semantic model | Equivalent to build permissions | Allows the user to share the content of the semantic model with other users who will get read, reshare, or explore permissions for it |
| ReadReshareExplore | 
|
|
|
| ReadReshare |
|
|
|
| ReadExplore |
|
|
|
| Read |
|
|
|
Note
To allow a user to perform write operations on a semantic model, first change the workspace permissions.
Build permissions and REST APIs
In the Power BI REST APIs, the build permission is returned as explore. For example, a string with the read, reshare and build permissions, will look like this: ReadReshareExplore.
When you give a user build permission, they can build new content on your semantic model. Examples of content they can build are reports, dashboards, pinned tiles from Q&A, paginated reports, and Insights Discovery.
Users also need build permissions to work with data outside Power BI:
To export the underlying data.
To build new content on the semantic model such as with Analyze in Excel.
To access the data via the XMLA endpoint.
Row-level security
For a semantic model that uses row-level security (RLS), any permissions higher than build will enable the user to view all the data in the semantic model. Build, and permissions lower than build, will only give the semantic model user access to the data they're allowed to see as configured in your RLS settings.
Get and update semantic model permissions with APIs
POST APIs let you add new permissions to a semantic model. You can use these APIs to add permissions for users but not to remove permissions. For example, you can add the
Resharepermission to a user that has theReadpermission. However, you can't remove theResharepermission from a user that has bothReadandResharepermissions, by attempting to add theReadpermission.PUT APIs update the user’s permissions to a given dataset. The PUT API can't be used for changing write permissions or any folder level inherited permissions. This API also supports removing all permissions for a dataset for a given target.
GET APIs return a list of principals that have access to the specified dataset.
Considerations and limitations
Each of the above APIs comes with certain limitations regarding who can use them and how. To see the limitations of each API, select the link for that API.