Power BI User Management API Guide

Auth method: OAuth 2.0 (Azure AD / Microsoft Entra ID; Bearer token)

Setup steps

1. Register an application in Microsoft Entra ID (Azure AD) at https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps.
2. Grant the application the required Power BI Service API permissions (Delegated or Application) under API permissions.
3. For Application (service principal) flows, grant admin consent for the tenant.
4. Acquire an access token via the Microsoft identity platform token endpoint: POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token with client_credentials or authorization_code grant.
5. Pass the token as 'Authorization: Bearer {token}' on all Power BI REST API requests.
6. For admin endpoints, the calling identity must be assigned the Power BI Service Administrator or Fabric Administrator role in Entra ID.

Required scopes

List workspace users

• Method: GET
• URL: https://api.powerbi.com/v1.0/myorg/groups/{groupId}/users
• Watch out for: Requires Workspace.Read.All or Workspace.ReadWrite.All scope. Service principal must be enabled for admin APIs in tenant settings.

Request example

GET /v1.0/myorg/groups/{groupId}/users
Authorization: Bearer {token}

Response example

{
  "value": [
    {
      "identifier": "user@contoso.com",
      "principalType": "User",
      "groupUserAccessRight": "Member",
      "displayName": "Jane Doe",
      "emailAddress": "user@contoso.com"
    }
  ]
}

Add user to workspace

• Method: POST
• URL: https://api.powerbi.com/v1.0/myorg/groups/{groupId}/users
• Watch out for: User must already exist in the Entra ID tenant. Adding a Free-licensed user to a Pro workspace does not auto-assign a Pro license.

Request example

POST /v1.0/myorg/groups/{groupId}/users
Content-Type: application/json
{
  "identifier": "user@contoso.com",
  "principalType": "User",
  "groupUserAccessRight": "Member"
}

Response example

HTTP 200 OK
(empty body on success)

Update workspace user role

• Method: PUT
• URL: https://api.powerbi.com/v1.0/myorg/groups/{groupId}/users
• Watch out for: Uses PUT (full replacement of role), not PATCH. The identifier must exactly match the existing member.

Request example

PUT /v1.0/myorg/groups/{groupId}/users
Content-Type: application/json
{
  "identifier": "user@contoso.com",
  "principalType": "User",
  "groupUserAccessRight": "Admin"
}

Response example

HTTP 200 OK
(empty body on success)

Remove user from workspace

• Method: DELETE
• URL: https://api.powerbi.com/v1.0/myorg/groups/{groupId}/users/{user}
• Watch out for: The {user} path segment must be URL-encoded. Removing the last Admin from a workspace is blocked.

Request example

DELETE /v1.0/myorg/groups/{groupId}/users/user%40contoso.com
Authorization: Bearer {token}

Response example

HTTP 200 OK
(empty body on success)

Admin: List all workspace users (admin)

• Method: GET
• URL: https://api.powerbi.com/v1.0/myorg/admin/groups/{groupId}/users
• Watch out for: Requires Tenant.Read.All or Tenant.ReadWrite.All and the caller must be a Power BI / Fabric admin. Subject to 200 req/hr admin throttle.

Request example

GET /v1.0/myorg/admin/groups/{groupId}/users
Authorization: Bearer {token}

Response example

{
  "value": [
    {
      "identifier": "user@contoso.com",
      "principalType": "User",
      "groupUserAccessRight": "Admin",
      "licenseType": "Pro"
    }
  ]
}

Admin: Get user artifact access

• Method: GET
• URL: https://api.powerbi.com/v1.0/myorg/admin/users/{userId}/artifactAccess
• Watch out for: Paginated via continuationToken. {userId} is the Entra ID object GUID, not UPN.

Request example

GET /v1.0/myorg/admin/users/{userId}/artifactAccess
Authorization: Bearer {token}

Response example

{
  "artifactAccessEntities": [
    {
      "artifactId": "guid",
      "displayName": "Sales Report",
      "artifactType": "Report",
      "accessRight": "ReadWrite"
    }
  ],
  "continuationToken": "..."
}

Admin: Get user subscriptions

• Method: GET
• URL: https://api.powerbi.com/v1.0/myorg/admin/users/{userId}/subscriptions
• Watch out for: Admin-only endpoint. Requires Tenant.Read.All scope.

Request example

GET /v1.0/myorg/admin/users/{userId}/subscriptions
Authorization: Bearer {token}

Response example

{
  "subscriptionEntities": [
    {
      "id": "guid",
      "title": "Weekly Sales",
      "artifactDisplayName": "Sales Dashboard"
    }
  ],
  "continuationToken": "..."
}

Admin: Add/update workspace user (admin override)

• Method: POST
• URL: https://api.powerbi.com/v1.0/myorg/admin/groups/{groupId}/users
• Watch out for: Admin variant bypasses workspace-level permission checks. Requires Tenant.ReadWrite.All and Fabric/Power BI admin role.

Request example

POST /v1.0/myorg/admin/groups/{groupId}/users
Content-Type: application/json
{
  "identifier": "user@contoso.com",
  "principalType": "User",
  "groupUserAccessRight": "Admin"
}

Response example

HTTP 200 OK
(empty body on success)

• Rate limits: Power BI REST API enforces per-call throttling. Admin APIs have a documented limit of 200 requests per hour per tenant for most bulk/admin operations. Standard APIs follow general Azure throttling policies. Exceeding limits returns HTTP 429.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 429 responses include a Retry-After header. Admin bulk APIs (e.g., GetGroupsAsAdmin with $expand) have additional documented throttling. Microsoft recommends exponential backoff.
• Pagination method: token
• Default page size: 100
• Max page size: 5000
• Pagination pointer: $top / continuationToken

• Webhooks available: No
• Webhook notes: Power BI does not offer native outbound webhooks for user-management events (e.g., user added/removed from workspace).
• Alternative event strategy: Use Microsoft Entra ID audit logs or Microsoft Purview activity events via the Power BI Activity Events API (GET /v1.0/myorg/admin/activityevents) to poll for user-related actions such as AddGroupMembers or DeleteGroupMembers.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Power BI Pro or Premium Per User (PPU); Microsoft Entra ID P1 or P2 required for automated provisioning

• Endpoint: Handled natively by Microsoft Entra ID provisioning (not a standalone Power BI SCIM endpoint). Entra ID provisions users into the Microsoft 365 tenant; Power BI licenses are then assigned via Entra ID group-based licensing.

• Supported operations: Create user (provision Entra ID account), Update user attributes, Deactivate/disable user, Group membership sync

Limitations:

• No dedicated Power BI SCIM endpoint; provisioning targets Entra ID, not Power BI directly.
• Power BI workspace membership is not managed via SCIM; use the Power BI REST API or Entra ID security groups mapped to workspaces.
• License assignment (Pro/PPU) must be configured separately via Entra ID group-based licensing or direct assignment.
• Guest (B2B) user provisioning has additional constraints in Entra ID.
• Supported IdPs for Entra ID SCIM provisioning: Okta, OneLogin, and others via the Entra ID app gallery.

Three scenarios cover the majority of programmatic user-management needs.

Onboarding: Provision the Entra ID account via SCIM from your IdP, assign a Pro or PPU license via Microsoft Graph or M365 Admin Center, then call POST /v1.0/myorg/groups/{groupId}/users with principalType: 'User' and the target groupUserAccessRight. License propagation can take several minutes; workspace add calls made before propagation completes will succeed at the API level but the user will encounter access errors until the license is active.

Offboarding: Disabling the Entra ID account blocks login but does not remove Power BI workspace memberships. Explicit removal via DELETE /v1.0/myorg/groups/{groupId}/users/{userUPN} is required for each workspace. Use GET /v1.0/myorg/admin/users/{userId}/artifactAccess to enumerate all workspaces and artifacts before issuing deletes. The admin API throttle of 200 requests/hour per tenant will constrain bulk offboarding across large workspace counts; implement exponential backoff on HTTP 429 responses.

Access auditing: GET /v1.0/myorg/admin/groups/{groupId}/users returns licenseType and userType fields only in the admin variant - the standard /groups/{groupId}/users endpoint omits them. Pagination uses an opaque continuationToken, not numeric offset; always check for its presence in responses before assuming a result set is complete.

Onboard a new employee to a Power BI workspace

1. Provision the user in Entra ID (via SCIM from IdP or manual creation).
2. Assign a Power BI Pro or PPU license via Microsoft 365 admin center or Entra ID group-based licensing.
3. Call POST /v1.0/myorg/groups/{groupId}/users with the user's UPN, principalType: 'User', and the desired groupUserAccessRight (e.g., 'Member').
4. Verify membership with GET /v1.0/myorg/groups/{groupId}/users.

Watch out for: Step 2 (license assignment) must complete before the user can access Pro-gated content. License propagation can take several minutes.

Offboard a departing employee from all workspaces

1. Disable or delete the user account in Entra ID (via SCIM deprovisioning or manual action).
2. Use GET /v1.0/myorg/admin/users/{userId}/artifactAccess to enumerate all workspaces and artifacts the user has access to.
3. For each workspace, call DELETE /v1.0/myorg/groups/{groupId}/users/{userUPN} to remove membership.
4. Revoke any dataset permissions via DELETE /v1.0/myorg/datasets/{datasetId}/users/{userUPN}.
5. Confirm removal with GET /v1.0/myorg/admin/groups/{groupId}/users.

Watch out for: Disabling the Entra ID account blocks login but does not remove Power BI workspace memberships. Explicit removal via the REST API is required for clean offboarding. Admin API throttle (200 req/hr) may slow bulk operations across many workspaces.

Audit all users with access to a sensitive workspace

1. Authenticate as a Power BI / Fabric admin with Tenant.Read.All scope.
2. Call GET /v1.0/myorg/admin/groups/{groupId}/users to retrieve all members and their roles.
3. For each user, optionally call GET /v1.0/myorg/admin/users/{userId}/artifactAccess to enumerate artifact-level permissions.
4. Cross-reference licenseType and userType fields to identify guest or Free-licensed users with elevated roles.
5. Export results and compare against expected access list.

Watch out for: The admin/groups/{groupId}/users endpoint returns licenseType only in the admin variant, not the standard /groups/{groupId}/users endpoint. Pagination via continuationToken is required for workspaces with large membership.

The most common integration failure is treating Entra ID group membership and Power BI workspace membership as equivalent. An automation that adds users to an Entra ID security group will not propagate those users into Power BI workspaces unless the workspace is explicitly backed by a Microsoft 365 group.

Automations that skip the POST /groups/{groupId}/users step produce users who have a valid license but no workspace access, with no error surfaced to the provisioning system.

The admin API throttle is a second failure point. The 200 requests/hour per tenant limit applies to all admin endpoints collectively, not per-caller. An offboarding job iterating across dozens of workspaces can exhaust the quota and block other admin API consumers in the same tenant.

Batch operations and off-peak scheduling are necessary mitigations.

Finally, the SCIM integration targets Entra ID, not Power BI directly. There is no standalone Power BI SCIM endpoint.

SCIM provisioning from Okta, OneLogin, or other IdPs provisions the Entra ID account and syncs attributes; Power BI license assignment and workspace membership remain separate post-provisioning steps that must be handled via Entra ID group-based licensing and the Power BI REST API respectively.