Share via

Groups - Add Group User

Service:
Power BI REST APIs
API Version:
v1.0

Grants the specified user the specified permissions to the specified workspace.

Permissions

This API call can be called by a service principal profile. For more information see: Service principal profiles in Power BI Embedded.

Required Scope

Workspace.ReadWrite.All

Limitations

  • User permissions for workspaces take time to get updated and may not be immediately available when using API calls. To refresh user permissions, use the Refresh User Permissions API call.
  • Each workspace is limited to a maximum of 1,000 users or groups in workspace roles (Admin, Member, Contributor, Viewer). The number of users within a group is not limited. The limitation also covers external guests. 

POST https://api.powerbi.com/v1.0/myorg/groups/{groupId}/users

URI Parameters

Name In Required Type Description
groupId
 path True

string (uuid)

The workspace ID

Request Body

Name Required Type Description
groupUserAccessRight True

GroupUserAccessRight

The access right (permission level) that a user has on the workspace
identifier True

string

Identifier of the principal
principalType True

PrincipalType

The principal type
displayName

string

Display name of the principal
emailAddress

string

Email address of the user
graphId

string

Identifier of the principal in Microsoft Graph. Only available for admin APIs.
profile

ServicePrincipalProfile

A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
userType

string

Type of the user.

Responses

Name Type Description
200 OK

OK

Examples

Assign administrator user access rights to a service principal example
Example

Assign administrator user access rights to a service principal example

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/users
Request Body
{
  "identifier": "1f69e798-5852-4fdd-ab01-33bb14b6e934",
  "groupUserAccessRight": "Admin",
  "principalType": "App"
}

Sample response

Status code:
200

Example

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/users
Request Body
{
  "emailAddress": "john@contoso.com",
  "groupUserAccessRight": "Admin"
}

Sample response

Status code:
200

Definitions

Name Description
GroupUser

A Power BI user with access to the workspace
GroupUserAccessRight

The access right (permission level) that a user has on the workspace
PrincipalType

The principal type
ServicePrincipalProfile

A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.

GroupUser

Object

A Power BI user with access to the workspace

Name Type Description
displayName

string

Display name of the principal
emailAddress

string

Email address of the user
graphId

string

Identifier of the principal in Microsoft Graph. Only available for admin APIs.
groupUserAccessRight

GroupUserAccessRight

The access right (permission level) that a user has on the workspace
identifier

string

Identifier of the principal
principalType

PrincipalType

The principal type
profile

ServicePrincipalProfile

A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
userType

string

Type of the user.

GroupUserAccessRight

Enumeration

The access right (permission level) that a user has on the workspace

Value Description
None

No access to workspace content
Member

Read, reshare and explore (ReadReshareExplore) access rights to workspace content
Admin

Administrator rights to workspace content
Contributor

Read and explore (ReadExplore) access to workspace content
Viewer

Read-only (Read) access to workspace content

PrincipalType

Enumeration

The principal type

Value Description
None

No principal type. Use for whole organization level access.
User

User principal type
Group

Group principal type
App

Service principal type

ServicePrincipalProfile

Object

A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.

Name Type Description
displayName

string

The service principal profile name
id

string (uuid)

The service principal profile ID