Groups - Add Group User

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
{
  "identifier": "1f69e798-5852-4fdd-ab01-33bb14b6e934",
  "groupUserAccessRight": "Admin",
  "principalType": "App"
}

Sample response

Example

Sample request

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

Sample response

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