Datasets permissions

This article describes Power BI permissions in general, and dataset 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 datasets 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 datasets 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:

Item permissions

Power BI items, such as reports, datasets, 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.

Dataset permissions and REST APIs

Dataset permissions are part of the item permissions. The table below lists the Power BI dataset 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 dataset Equivalent to build permissions Allows the user to share the content of the dataset 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 dataset, 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 dataset. 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 dataset such as with Analyze in Excel.

  • To access the data via the XMLA endpoint.

Row-level security

For a dataset that uses row-level security (RLS), any permissions higher than build will enable the user to view all the data in the dataset. Build, and permissions lower than build, will only give the dataset user access to the data they're allowed to see as configured in your RLS settings.

Get and update dataset permissions with APIs

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.

Next steps