Groups - Add Group User

  • Reference
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. 

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

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

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

Name Type Description
Admin

string

Administrator rights to workspace content
Contributor

string

Read and explore (ReadExplore) access to workspace content
Member

string

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

string

No access to workspace content
Viewer

string

Read-only (Read) access to workspace content

PrincipalType

The principal type

Name Type Description
App

string

Service principal type
Group

string

Group principal type
None

string

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

string

User principal type

ServicePrincipalProfile

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

The service principal profile ID