Tell us about your PDF experience.

Power BI embedded analytics

documentation
Learn to use the two Power BI embedded analytics solutions, Power BI Embedded, and
embedding using Power BI Premium.

Get started

ｂ GET STARTED

What is Power BI embedded analytics?

Frequently asked questions

ｈ WHAT'S NEW

Multitenancy solutions

ｉ REFERENCE

Power BI Developer in a Day course

Client APIs

ｈ WHAT'S NEW

Power BI embedded analytics Client APIs

Embed reports or dashboards

ｇ TUTORIAL

Tutorial: Embed Power BI content into an application for your customers

Tutorial: Embed a Power BI report in an application for your organization

ｃ HOW-TO GUIDE

Embed Power BI paginated reports

Embed using a service principal

ｉ REFERENCE

Embedding setup tool

Developer samples and scripts

Plan for production

Ｙ ARCHITECTURE

Capacity and SKUs

Capacity planning

ｐ CONCEPT

Performance best practices

Power BI permissions

Questions and answers

Troubleshoot your embedded application

References and resources

ｈ WHAT'S NEW

Playground

ｉ REFERENCE

Power BI REST APIs

Developer center

Power BI libraries

Power BI embedded analytics Client APIs

Learn
ｄ TRAINING

Power BI Dev Camp

ｉ REFERENCE

Dev Camp website

What is Power BI embedded analytics?
Article • 03/14/2024

APPLIES TO: App owns data User owns data

Power BI embedded analytics allows you to embed your Power BI items such as reports,
dashboards and tiles, in a web application or in a website. You can:

Deliver compelling data experiences for your end users, enabling them to take
action based on insights from your solutions data.

Quickly and easily provide exceptional customer-facing reports, dashboards, and

analytics in your own apps by using and branding Power BI as your own.

Secure embed
Secure embed is the simplest no-code way to embed a report into any portal that
accepts a URL or iFrame. The viewer of the report must have the proper Power BI license.
The viewer can interact with the report, but not edit, save, or make any changes to it.
Secure embed is available in the Power BI service.

For more advanced solutions that give your users more flexibility and control, use one of
the Power BI embedded analytics solutions described in this article.

What are the Power BI embedded analytics

solutions?
Power BI embedded analytics gives you additional benefits over secure embed. It offers
a rich, fully integrated experience with full API support, automatic authentication, and
the reports can be hosted in apps as well as web pages. Embedded analytics allows you
to automate the monitoring, management, and deployment of analytics, while getting
full control of Power BI features and intelligent analytics.

Power BI Embedded has basically the same features as Power BI Premium.

Power BI embedded analytics offers two solutions:

Embed for your customers

Embed for your organization

Embed for your customers
The embed for your customers solution allows you to build an app that uses non-
interactive authentication against Power BI. Your customers are likely to be external
users, and they don't need to sign in using Power BI credentials to view the embedded
content. Typically, this solution is used by independent software vendors (ISVs) who are
developing applications for third parties. For a tutorial, see Embed Power BI content
using a sample embed for your customers application.

Embed for your organization

The embed for your organization solution allows you to build an app that requires
signing in using Power BI credentials. Once signed in users can only consume
embedded content, they have access to on Power BI service. This solution is aimed at
large organizations that are building an app for internal users. For a tutorial, see Embed
Power BI content into an application for your organization.

Comparison of the embed for your customers vs

embed for your organization solutions
The following table provides a comparison between the two Power BI embedded
analytics solutions.

ﾉ Expand table

Embed for your customers Embed for your organization

Also known as app owns data Also known as user owns data

Aimed at external users Aimed at internal users

To authenticate app users, use your own App users authenticate against Microsoft
authentication method Entra ID

App users don't need a license Each app user needs a Power BI license

Non-interactive authentication. Your app uses a Interactive authentication. Your app uses the
service principal or a master user to authenticate app user's credentials to authenticate

 Tip

Get started with the Power BI embedded analytics setup tool .

What are Power BI capacities?
A capacity is a set of resources reserved for exclusive use. It enables you to publish
dashboards, reports, and semantic models to users, without having to purchase per-user
licenses. It also offers dependable, consistent performance for your content.
For development testing, you can use free embed trial tokens with a Pro license. To
embed in a production environment, you must use a capacity.

） Important

Free trial tokens are limited to development testing only. Once going to
production, a capacity must be purchased. Until a capacity is purchased, the Free
trial version banner will continue to appear at the top of the embedded report.

There are two types of Power BI embedded analytics offerings. Each offer includes a
different type of SKU that you use to buy a Power BI capacity:

Power BI Embedded is an Azure offer that includes A SKUs. Power BI Embedded is

associated with the embed for your customers solution.

Power BI Premium is a Microsoft Office offer that includes P or EM SKUs.

For more information about the differences between the Embedded and Premium SKUs,
see Capacity and SKUs in Power BI embedded analytics.

Related content
Capacity and SKUs in Power BI embedded analytics
Tutorial: Embed Power BI content using a sample embed for your customers
application
Tutorial: Embed Power BI content using a sample embed for your organization
application
Power BI embedded analytics setup tool

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Fabric operations
Article • 03/10/2024

Each experience within Microsoft Fabric supports unique operations. An operation's consumption rate is what
converts the usage of the experience's raw metrics into Compute Units (CU).

The Microsoft Fabric Capacity Metrics app's compute page provides an overview of your capacity's
performance and lists Fabric operations that consume compute resources.

This article lists these operations by experience, and explains how they consume resources within Fabric.

Interactive and background operations

Microsoft Fabric divides operations into two types, interactive and background. This article lists these
operations and explains the difference between them.

Interactive operations
On-demand requests and operations that can be triggered by user interactions with the UI, such as data
model queries generated by report visuals, are classified as interactive operations. They're usually triggered by
user interactions with the UI. For example, an interactive operation is triggered when a user opens a report or
clicks on a slicer in a Power BI report. Interactive operations can also be triggered without interacting with the
UI, for example when using SQL Server Management Studio (SSMS) or a custom application to run a DAX
query.

Background operations
Longer running operations such as semantic model or dataflow refreshes are classified as background
operations. They can be triggered manually by a user, or automatically without user interaction. Background
operations include scheduled refreshes, interactive refreshes, REST-based refreshes and XMLA-based refresh
operations. Users aren't expected to wait for these operations to finish. Instead, they might come back later to
check the status of the operations.

How to read this document

Each experience has a table that lists its operations, with the following columns:

Operation – The name of the operation. Visible in the Microsoft Fabric Capacity Metrics app.

Description – A description of the operation.

Item – The item that this operation can apply to. Visible in the Microsoft Fabric Capacity Metrics app.

Azure billing meter – The name of the meter on your Azure bill that shows usage for this operation.

Type – Lists the type of the operation. Operations are classified as interactive or background operations.

When more details regarding the consumption rate are available, a link to the document with this information
is provided.
Fabric operations by experience
This section is divided into Fabric experience. Each experience had a table that lists its operations.

） Important

Consumption rates are subject to change at any time. Microsoft will use reasonable efforts to provide
notice via email or through in-product notification. Changes shall be effective on the date stated in
Microsoft's Release Notes or Microsoft Fabric blog . If any change to a Microsoft Fabric Workload
Consumption Rate materially increases the Capacity Units (CU) required to use a particular workload,
customers might use the cancellation options available for the chosen payment method.

Copilot in Fabric
Copilot operations are listed in this table. You can find the consumption rates for Copilot in Copilot
consumption.

ﾉ Expand table

Operation Description Item Azure billing Type

meter

Copilot in Compute cost associated with input prompts and output Multiple Copilot in Fabric Background
Fabric completion CU

Data Factory
The Data Factory experience contains operations for Dataflows Gen2 and Pipelines.

Dataflows Gen2
You can find the consumption rates for Dataflows Gen2 in Dataflow Gen2 pricing for Data Factory in Microsoft
Fabric.

ﾉ Expand table

Operation Description Item Azure billing meter Type

Dataflow Gen2 Refresh Compute cost associated with Dataflow Dataflows Standard Background
dataflow Gen2 refresh Gen2 Compute Capacity
operation Usage CU

High Scale Dataflow Compute - Usage related to the dataflow Warehouse High Scale Dataflow Background
SQL Endpoint Query Gen2 staging warehouse SQL Compute Capacity
endpoint Usage CU

Pipelines
You can find the consumption rates for Pipelines in Data pipelines pricing for Data Factory in Microsoft Fabric.
 ﾉ Expand table

Operation Description Item Azure billing meter Type

DataMovement The amount of time used by the copy activity in a Pipeline Data Movement Background
Data Factory pipeline divided by the number of data Capacity Usage CU
integration units

ActivityRun A Data Factory data pipeline activity execution Pipeline Data Orchestration Background
Capacity Usage CU

Data Warehouse
One Synapse Data Warehouse core (unit of compute for Data Warehouse) is equivalent to two Fabric Capacity
Units (CUs).

ﾉ Expand table

Operation Description Item Azure billing meter Type

Warehouse Compute charge for all user generated and system Warehouse Data Warehouse Background
Query generated T-SQL statements within a Warehouse Capacity Usage CU

SQL Endpoint Compute charge for all user generated and system Warehouse Data Warehouse Background
Query generated T-SQL statements within a SQL Endpoint Capacity Usage CU

Fabric API for GraphQL

GraphQL operations are made up of requests performed on API for GraphQL items by API clients. Each
GraphQL request and response operation processing time is reported in Capacity Units (CUs) in seconds at the
rate of ten CUs per hour.

ﾉ Expand table

Operation Description Item Azure billing meter Type

Query Compute charge for all generated GraphQL queries GraphQL API for GraphQL Query Interactive
(reads) and mutations (writes) by clients within a GraphQL Capacity Usage CU
API

OneLake
One Lake compute operations represent the transactions performed on One Lake items. The consumption rate
for each operation varies depending on its type. For more details, refer to One Lake consumption.

ﾉ Expand table

Operation Description Item Azure Type

Billing
Meter

OneLake Read via Redirect OneLake Read via Redirect (Multiple) OneLake Background
Read
Operations
Operation Description Item Azure Type
Billing
Meter

Capacity
Usage CU

OneLake Read via Proxy OneLake Read via Proxy (Multiple) OneLake Background
Read
Operations
via API
Capacity
Usage CU

OneLake Write via Redirect OneLake Write via Redirect (Multiple) OneLake Background
Write
Operations
Capacity
Usage CU

OneLake Write via Proxy OneLake Write via Proxy (Multiple) OneLake Background
Write
Operations
via API
Capacity
Usage CU

OneLake Iterative Write via Redirect OneLake Iterative Write via Redirect (Multiple) OneLake Background
Iterative
Write
Operations

OneLake Iterative Read via Redirect OneLake Iterative Read via Redirect (Multiple) OneLake Background
Iterative
Read
Operations
Capacity
Usage CU

OneLake Other Operations OneLake Other Operations (Multiple) OneLake Background

Other
Operations
Capacity
Usage CU

OneLake Other Operations via Redirect OneLake Other Operations via Redirect (Multiple) OneLake Background
Other
Operations
via API
Capacity
Usage CU

OneLake Iterative Write via Proxy OneLake Iterative Write via Proxy (Multiple) OneLake Background
Iterative
Write
Operations
via API
Capacity
Usage CU

OneLake Iterative Read via Proxy OneLake Iterative Read via Proxy (Multiple) OneLake Background
Iterative
Operation Description Item Azure Type
Billing
Meter

Read
Operations
via API
Capacity
Usage CU

OneLake BCDR Read via Proxy OneLake BCDR Read via Proxy (Multiple) OneLake Background
BCDR
Read
Operations
via API
Capacity
Usage CU

OneLake BCDR Write via Proxy OneLake BCDR Write via Proxy (Multiple) OneLake Background
BCDR
Write
Operations
via API
Capacity
Usage CU

OneLake BCDR Read via Redirect OneLake BCDR Read via Redirect (Multiple) OneLake Background
BCDR
Read
Operations
Capacity
Usage CU

OneLake BCDR Write via Redirect OneLake BCDR Write via Redirect (Multiple) OneLake Background
BCDR
Write
Operations
Capacity
Usage CU

OneLake BCDR Iterative Read via Proxy OneLake BCDR Iterative Read via Proxy (Multiple) OneLake Background
BCDR
Iterative
Read
Operations
via API
Capacity
Usage CU

OneLake BCDR Iterative Read via Redirect OneLake BCDR Iterative Read via Redirect (Multiple) OneLake Background
BCDR
Iterative
Read
Operations
Capacity
Usage CU

OneLake BCDR Iterative Write via Proxy OneLake BCDR Iterative Write via Proxy (Multiple) OneLake Background
BCDR
Iterative
Write
Operations
 Operation Description Item Azure Type
Billing
Meter

via API
Capacity
Usage CU

OneLake BCDR Iterative Write via Redirect OneLake BCDR Iterative Write via Redirect (Multiple) OneLake Background
BCDR
Iterative
Write
Operations
Capacity
Usage CU

OneLake BCDR Other Operations OneLake BCDR Other Operations (Multiple) OneLake Background
BCDR
Other
Operations
Capacity
Usage CU

OneLake BCDR Other Operations Via Redirect OneLake BCDR Other Operations Via Redirect (Multiple) OneLake Background
BCDR
Other
Operations
via API
Capacity
Usage CU

Power BI
The usage for each operation is reported in CU processing time in seconds. Eight CUs are equivalent to one
Power BI v-core.

７ Note

The term Semantic model replaces the term dataset. You may still see the old term in the UI until it is
completely replaced.

ﾉ Expand table

Operation Description Item Azure billing Type

meter

Artificial intelligence AI function evaluation AI Power BI Background

(AI) Capacity
Usage CU

Background query Queries for refreshing tiles and creating report Semantic Power BI Background
snapshots model Capacity
Usage CU

Dataflow DirectQuery Connect directly to a dataflow without the need to Dataflow Power BI Interactive
import the data into a semantic model Gen1 Capacity
Usage CU
 Operation Description Item Azure billing Type
meter

Dataflow refresh An on-demand or scheduled background dataflow Dataflow Power BI Background

refresh, performed by the service or with REST APIs. Gen1 Capacity
Usage CU

Semantic model on- A background semantic model refresh initiated by Semantic Power BI Background
demand refresh the user, using the service, REST APIs, or public model Capacity
XMLA endpoints Usage CU

Semantic model A scheduled background semantic model refresh, Semantic Power BI Background
scheduled refresh performed by the service, REST APIs, or public XMLA model Capacity
endpoints Usage CU

Full report email A PDF or PowerPoint copy of an entire Power BI Report Power BI Background
subscription report, attached to an email subscription Capacity
Usage CU

Interactive query Queries initiated by an on-demand data request Semantic Power BI Interactive
from a user. For example, loading a model when model Capacity
opening a report, or user interaction with a report Usage CU

PublicApiExport A Power BI report exported with the export report to Report Power BI Background
file REST API Capacity
Usage CU

Render A Power BI paginated report exported with Paginated Power BI Background

the export paginated report to file REST API report Capacity
Usage CU

Render A Power BI paginated report viewed in Power BI Paginated Power BI Interactive

service report Capacity
Usage CU

Web modeling read A data model read operation in the semantic model Semantic Power BI Interactive
web modeling user experience model Capacity
Usage CU

Web modeling write A data model write operation in the semantic model Semantic Power BI Interactive
web modeling user experience model Capacity
Usage CU

XMLA read XMLA read operations initiated by the user, for Semantic Power BI Interactive
queries and discoveries model Capacity
Usage CU

XMLA write A background XMLA write operation that changes Semantic Power BI Background
the model model Capacity
Usage CU

Real-Time Intelligence
The Real-Time Intelligence experience contains operations for Event streams and KQL Database and KQL
Queryset.

Event streams
You can find the consumption rates for Event streams in Monitor capacity consumption for Microsoft Fabric
event streams.

ﾉ Expand table

Operation Description Item Azure billing meter Type

Eventstream Per Hour Ingestion or processing for Event eventstream Capacity Usage CU Background
Event Stream Stream

Eventstream Data Traffic Data Ingress and Egress Event eventstream Data Traffic per GB Background
per GB Stream Capacity Usage CU

Eventstream Processor ASA Processing Event eventstreams Processor Capacity Background

Per Hour Stream Usage CU

KQL Database and KQL Queryset

You can find the consumption rates for KQL Database in KQL Database consumption.

ﾉ Expand table

Operation Description Item Azure billing meter Type

KustoUpTime Measure of the time that the KQL KQL Database or KQL KQL Database Capacity Interactive
database is Active Queryset Usage CU

Spark
Two Spark VCores (a unit of computing power for Spark) equals one capacity unit (CU). To understand how
Spark operations consume CUs, refer to spark pools.

ﾉ Expand table

Operation Description Item Azure billing meter Type

Lakehouse Users preview table in the Lakehouse Lakehouse Spark Memory Optimized Background
operations explorer Capacity Usage CU

Lakehouse table Users load delta table in the Lakehouse Lakehouse Spark Memory Optimized Background
load explorer Capacity Usage CU

Notebook run Synapse Notebook runs manually by Synapse Spark Memory Optimized Background
users Notebook Capacity Usage CU

Notebook HC run Synapse Notebook runs under the high Synapse Spark Memory Optimized Background
concurrency Spark session Notebook Capacity Usage CU

Notebook Synapse Notebook runs triggered by Synapse Spark Memory Optimized Background
scheduled run notebook scheduled events Notebook Capacity Usage CU

Notebook Synapse Notebook runs triggered by Synapse Spark Memory Optimized Background
pipeline run pipeline Notebook Capacity Usage CU

Notebook VS Synapse Notebook runs in VS Code. Synapse Spark Memory Optimized Background
Code run Notebook Capacity Usage CU
 Operation Description Item Azure billing meter Type

Spark job run Spark batch job runs initiated by user Spark Job Spark Memory Optimized Background
submission Definition Capacity Usage CU

Spark job Synapse batch job runs triggered by Spark Job Spark Memory Optimized Background
scheduled run notebook scheduled events Definition Capacity Usage CU

Spark job Synapse batch job runs triggered by Spark Job Spark Memory Optimized Background
pipeline run pipeline Definition Capacity Usage CU

Spark job VS Synapse Spark job definition submitted Spark Job Spark Memory Optimized Background
Code run from VS Code Definition Capacity Usage CU

Related content
What is the Microsoft Fabric Capacity Metrics app?

Understand the metrics app compute page

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Create a Power BI report in enhanced
report format
Article • 06/12/2024

APPLIES TO: Power BI Desktop Power BI service

The Power BI enhanced report format (PBIR) for Power BI Project files (PBIP) marks a
milestone in achieving the primary goal of Power BI Desktop developer mode. It
provides source-control friendly file formats to unblock codevelopment and enhance
development efficiency.

Power BI Projects (PBIP) support saving the report and semantic model into a folder
using source-control friendly formats:

PBIR for the report.

TMDL for the semantic model.

The PBIR file format simplifies tracking changes and resolving merge conflicts. It uses
properly formatted JSON and organizes each visual, page, bookmark, and so on, in
separate individual files within a folder structure.
 

You can enhance report development efficiency in one of two ways:

Copy and paste visuals, pages, bookmarks, or files between reports.

Apply manual or programmatic batch changes to the PBIR files.

Unlike PBIR-legacy format (report.json), PBIR is a publicly documented format. This

format allows modifications from non-Power BI applications. Each file has a public JSON
schema, which documents each property and lets code editors like Visual Studio Code
perform syntax validation while editing. On open, Power BI Desktop validates the
changed PBIR files to guarantee successful loading.

How to enable it
PBIR is currently in preview. You can only create or convert existing Power BI project files
to PBIR by using Power BI Desktop. You must first enable the feature in Power BI
Desktop preview features.

1. Go to File > Options and settings > Options > Preview features.
2. Check the box next to Store reports using enhanced metadata format (PBIR).

During preview, Fabric Git Integration and Fabric REST APIs continue to use PBIR-legacy
(report.json) when exporting the report definitions. However, if the report is imported
into Fabric using PBIR format, then both features start exporting the report definition
using PBIR format. At general availability (GA), PBIR will become the default report
format.
Limitations
Initially, the PBIR format has some service restrictions, such as these:

You can't publish the report in Power BI App.

You can't use subscriptions.
You can't download PBIX.

These restrictions should be removed in the following months.

Next steps
Power BI embedded analytics overview
The Power BI embedded analytics playground

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

What is the Power BI embedded
analytics playground?
Article • 03/03/2024

APPLIES TO: App owns data User owns data

The Power BI embedded analytics playground makes it easy for you to learn, explore,
and try out Power BI embedded analytics. It’s also where you can keep up with all the
new features and updates of Power BI embedded.

The playground gives you hands-on coding experience. It also lets you embed your own
reports and interact with Power BI client APIs that give you instant results.

The playground provides the following main experiences:

Developer sandbox
Explore the APIs
Showcases
Learning center

Developer sandbox
Go to the developer sandbox for hands-on experience using the client APIs. You can use
the APIs with the sample report or with your own report.
Drag and drop code snippets into the report or type them directly into the code editor
area to see how they work.

You can choose between JavaScript and TypeScript for writing your code. All API code
snippets then update based on your selection. The last language you use saves for next
time.
Explore our APIs
You can interact with code snippets and embed reports, dashboards, Q&As, and more in
Explore our APIs.

Showcases
The interactive showcases let you see how to apply these features in your applications.
Each showcase presents an application that demonstrates what you can do with one or
more of the client APIs.
The showcases code is open-sourced, and you can find the code behind all of them in
our GitHub repository .

Embedded Demo
The Embedded Demo is a great way for developers to quickly and easily get an idea
how Power BI Embedded would look and feel in their own apps without any need for
prior setup or configuration. First, go through the demo to generate your code and run
it in your app. Then, when you're ready, select the best solution for your needs and get
started with development.

Create demo code

Choose your solution

Create demo code

Select one of your own reports or use the provided sample report. The demo will
generate a code snippet that you can use to embed the report in your own app. You can
either copy the code into an existing app, or paste it into a new, blank one if you're still
developing your app. This demo gives you a hands-on look at the power of Power BI
Embedded.

Choose your solution

Once you're happy with the look and feel of the report in your app, visit the Power BI
Embedded Analytics Solutions page to gain a deeper understanding of which solution is
best for your needs. Choose between embedding Power BI for your organization or for
your customers. After you decide, you can start developing your own engaging,
powerful, and interactive Power BI Embedded reports and solutions.

Learning center
The Learning center is a collection of Power BI embedded analytics resources. It's where
you can dive into the documentation, learn about the APIs, find developer samples and
videos, and learn where to get help.

Related content
Explore the embedded analytics playground
Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Create a Microsoft Entra tenant to use
with Power BI
Article • 05/11/2024

APPLIES TO: App owns data User owns data

This article shows you how to create a new Microsoft Entra tenant to use when creating
a custom app that calls Power BI REST APIs.

A Microsoft Entra tenant is a reserved Microsoft Entra service instance that an

organization receives and owns once it signs up for a Microsoft cloud service such as
Azure, Microsoft Intune, or Microsoft 365. Each tenant represents an organization, and is
distinct and separate from other Microsoft Entra tenants.

Once you have a Microsoft Entra tenant, you can define an application and assign it
permissions so it can call Power BI REST APIs.

Your organization may already have a Microsoft Entra tenant that you can use for your
app, or you can create a new tenant specifically for your app. This article shows how to
create a new tenant.

Create a Microsoft Entra tenant

To integrate Power BI into your custom app, you need a Microsoft Entra directory. This
directory is your tenant. If your organization doesn't have a tenant, you need create one
as part of your dev environment. You should also create a tenant if you want to keep
things isolated and don't want your app mixing with your organization's tenant. Or, you
may just want to create a tenant for testing purposes.

To create a new Microsoft Entra tenant:

Follow the directions in Quickstart: Create a new tenant in Microsoft Entra ID to create a
new Microsoft Entra ID.

Provide the relevant Organization name, Initial domain name and Country/Region.

７ Note

Your initial domain is part of onmicrosoft.com. You can add other domain names
later. A tenant directory can have multiple domains assigned to it.
Create Microsoft Entra tenant users
When you create a new Microsoft Entra tenant, you become the first user of that tenant.
As the first user, you're automatically assigned the Global Admin role. Add new users by
navigating to the Users page.

Create a master user to use as your master embedding account. You can think of the
master user account as a service account.

1. In the home page of the Azure portal, select the Microsoft Entra ID tab.

2. Under Manage, select Users.

3. Under + New user select + Create new user.

4. Provide a Display Name and User name for your tenant Global Admin. Leave
Directory role as user. Note the password, then select Create.

5. Sign up for Power BI with the user account that you created in step 4. Go to
powerbi.com and select Try Power BI for free.

When you sign up, you're prompted to try Power BI Pro free for 60 days. You can
opt into that to become a Pro user, which gives you the option to start developing
 an embedded solution.

７ Note

Make sure you sign up with your user account's email address.

Related content
Now that you have a Microsoft Entra tenant, you can use this tenant to test items within
Power BI. You can also embed Power BI dashboards and reports in your app. For more
information, see How to embed your Power BI dashboards, reports, and tiles.

Register an app
Quickstart: Set up a dev environment

More questions? Try asking the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Set up Power BI Embedded
Article • 01/23/2024

APPLIES TO: App owns data User owns data

If you want to start using Power BI Embedded to share your reports with others, use the
Power BI embedded analytics setup tool to get started. This article shows you how.

To use Power BI embedded analytics, you need to register a Microsoft Entra application
in Azure. The Microsoft Entra app establishes permissions for Power BI REST resources,
and allows access to the Power BI REST APIs.

Prerequisite
To set up a Power BI embedded analytics environment, you need one of the following:

Microsoft Entra tenant and an organizational (master) user

Power BI Pro account

Before you begin

Before you can register your app, decide which of the following solutions best suits your
needs:

For your customers

For your organization

Embed for your customers

Use the embed-for-your-customers solution, also known as app owns data, if you create
an app that's designed for your customers. Users don't need to sign in to Power BI or
have a Power BI license to use your app. Your app authenticates against Power BI by
using either a master user account (a Power BI Pro license used for signing in to Power
BI) or a service principal.

The embed-for-your-customers solution is usually used by independent software

vendors (ISVs) and developers who create applications for a third party.

Embed for your organization

Use the embed-for-your-organization solution, also known as user owns data, if you
create an application that requires users to use their credentials to authenticate against
Power BI.

The embed-for-your-organization solution is usually used by enterprises and large

organizations, and is intended for internal users.

For more about the two solutions, see What are the Power BI embedded analytics
solutions?.

Set up your environment

After you understand the two embedding options, you can use the setup tool to create
your Power BI Embedded environment.

If you prefer to manually set up your environment, skip the steps in the following
sections. Instead, follow the steps in Manual registration, later in this article.

） Important

If you're embedding for a GCC, follow the instructions in Manual registration.

To use the tool to set up your environment, go to the Power BI embedded analytics
setup tool . Select the embedding option that you want.

Step 1 - Sign in to Power BI

1. Under Step 1 in the setup tool, select Sign in. This step signs you in to Power BI. If
you're prompted to pick an account, sign in with a user that belongs to your Power
BI tenant. The Microsoft Entra app gets registered under this user.

７ Note

If you're already signed in, verify that you're signed in with the user you want
to use to create the Microsoft Entra app. To change users, select sign out.
After the tool restarts, sign in with the correct user.

2. Select Next to go to the next step.

Step 2 - Register your application
In this step, you register a Microsoft Entra application in Azure. The Microsoft Entra app
establishes permissions for Power BI REST resources, and allows access to the Power BI
REST APIs. You can always change these settings at a later time.

Embed for your customers

1. To register your application for your customers, fill in the following fields:

Application Name - Give your application a name.

API access - Select the Power BI APIs (also known as scopes) that your
application needs. You can select Select all to select all the APIs. For
more information about Power BI access permissions, see Permissions
and consent in the Microsoft identity platform endpoint.
2. Select Register.

3. Your Microsoft Entra app Application ID is displayed in the Summary box.

Copy this value for later use.
Step 3 - Create a workspace (optional)
Create a workspace in the Power BI service:

If you already have a Power BI workspace, select Skip.

To create a workspace, enter a name for your workspace, and then select Create
workspace. Your workspace name and ID appear in the Summary box. Copy these
values for later use.

 Tip

For the embedded analytics sample app to work as expected, you have to
use the tool to create a workspace.

Step 4 - Import content (optional)

Select one of the following options:

If you have your own Power BI app, you can select Skip.

If you want to create a sample Power BI app by using a sample report, select
Sample Power BI report, and then select Import.

If you want to create a sample Power BI app by using your own report, select
Upload a .pbix file, browse for your file, and then select Import.

Step 5 - Grant permissions (Embed for your

customers only)
Select Grant permissions and in the dialog, select Accept. This step allows your
Microsoft Entra app to access the APIs you selected (also known as scopes) with your
signed-in user. This user is also known as the master user.

Download sample app (optional)

If you created a Power BI workspace and uploaded content to it by using this tool, you
can now select Download sample application.

７ Note
 If you skipped the optional stages, you can still download a sample Power BI app.
However, the code in the downloaded app lacks the properties that get filled in
during registration. For example, if you don't create a workspace, the sample app
doesn't include the workspace ID.

Make sure you copy all the information in the Summary box. Your Power BI embedding
environment is ready to use.

Manual registration
If you didn't use the Power BI embedded analytics setup tool, use the procedure in this
section to manually register a Microsoft Entra app. But take these steps only if you're
creating one of the following solutions:

An embed-for-your-organization application
An embed-for-your-customers application with a service principal

For more information about how to register applications in Microsoft Entra ID, see
Register an application with the Microsoft identity platform.

1. Sign in to the Azure portal .

2. Select your Microsoft Entra tenant by selecting your account in the upper-right
corner of the page.

3. Select App registrations. If you don't see this option, search for it.

4. In App registrations, select New registration.

5. Fill in the following fields:

Name - Give your application a name.

Supported account type - Select who can use the application.

6. (Optional) In the Redirect URI box, add a redirect URL.

7. Select Register. After your app is registered, you're directed to your app's overview
page, where you can obtain the Application ID.

Related content
More questions? Try asking the Power BI Community .
Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Configure credentials programmatically
for Power BI
Article • 05/21/2024

APPLIES TO: App owns data User owns data

To configure credentials programmatically for Power BI, follow the steps in this article.
Configuring credentials programmatically also allows you to encrypt credentials.

７ Note

The calling user must be a semantic model owner or a gateway admin. You
can also use a service principal. For example, the service principal can be the
semantic model owner.
Cloud data sources and their corresponding credentials are managed at the
user level.

Update the credentials flow for data sources

1. Discover the semantic model's data sources by calling Get Datasources. The
response body for each data source contains the type, connection details, gateway,
and data source ID.

C#

// Select a datasource
var datasources = pbiClient.Datasets.GetDatasources(datasetId).Value;
var datasource = datasources.First();

2. Build the credentials string according to the Update Datasource Examples. The
contents of the credentials string depends on the type of credentials.

.NET SDK v3

C#

var credentials = new BasicCredentials(username: "username",

password :"*****");
 ７ Note

If you're using cloud data sources, don't follow the next steps in this section.
Call Update Datasource to set the credentials by using the gateway ID and
data source ID that you obtained in step 1.

3. Retrieve the gateway public key by calling Get Gateway.

C#

var gateway = pbiClient.Gateways.GetGatewayById(datasource.GatewayId);

4. Encrypt the credentials.

.NET SDK v3

C#

var credentialsEncryptor = new

AsymmetricKeyEncryptor(gateway.publicKey);

5. Build the credential details with encrypted credentials.

.NET SDK v3

Use the AsymetricKeyEncryptor class with the public key retrieved in Step 3.

C#

var credentialDetails = new CredentialDetails(

credentials,
PrivacyLevel.Private,
EncryptedConnection.Encrypted,
credentialsEncryptor);

6. Set credentials by calling Update Datasource.

C#

pbiClient.Gateways.UpdateDatasource(datasource.GatewayId.Value,
datasource.DatasourceId.Value, new
UpdateDatasourceRequest(credentialDetails));
Configure a new data source for a data
gateway
1. Install the On-premises data gateway on your machine.

2. Retrieve the gateway ID and public key by calling Get Gateways.

C#

// Select a gateway
var gateways = pbiClient.Gateways.GetGateways().Value;
var gateway = gateways.First();

3. Build credential details by following the procedure that is described in the update
credentials flow for data sources section by using the gateway public key that you
retrieved in step 2.

4. Build the request body.

C#

var request = new PublishDatasourceToGatewayRequest(

dataSourceType: "SQL",
connectionDetails: "
{\"server\":\"myServer\",\"database\":\"myDatabase\"}",
credentialDetails: credentialDetails,
dataSourceName: "my sql datasource");

5. Call the Create Datasource API.

C#

pbiClient.Gateways.CreateDatasource(gateway.Id, request);

Credential types
When you call Create Datasource or Update Datasource from the Power BI REST API on
an enterprise on-premises gateway, encrypt the credentials value by using the gateway
public key.

７ Note
 .NET SDK v3 can also run the following .NET SDK v2 examples.

Windows and basic credentials

.NET SDK v3

C#

// Windows credentials
var credentials = new WindowsCredentials(username: "john", password:
"*****");

// Or

// Basic credentials
var credentials = new BasicCredentials(username: "john", password:
"*****");

var credentialsEncryptor = new AsymmetricKeyEncryptor(publicKey);

var credentialDetails = new CredentialDetails(credentials,
PrivacyLevel.Private, EncryptedConnection.Encrypted,
credentialsEncryptor);

Key credentials

.NET SDK v3

C#

var credentials = new KeyCredentials("TestKey");

var credentialsEncryptor = new AsymmetricKeyEncryptor(publicKey);
var credentialDetails = new CredentialDetails(credentials,
PrivacyLevel.Private, EncryptedConnection.Encrypted,
credentialsEncryptor);

OAuth2 credentials

.NET SDK v3

C#

var credentials = new OAuth2Credentials("TestToken");

var credentialsEncryptor = new AsymmetricKeyEncryptor(publicKey);
 var credentialDetails = new CredentialDetails(credentials,
PrivacyLevel.Private, EncryptedConnection.Encrypted,
credentialsEncryptor);

Anonymous credentials

.NET SDK v3

C#

var credentials = new AnonymousCredentials();

var credentialDetails = new CredentialDetails(credentials,
PrivacyLevel.Private, EncryptedConnection.NotEncrypted);

Troubleshooting

No gateway and data source ID are found when calling

get data sources
This issue means that the semantic model isn't bound to a gateway. When you create a
new semantic model, a data source with no credentials is created automatically on the
user's cloud gateway for each cloud connection. The cloud gateway is used to store the
credentials for cloud connections.

After you create the semantic model, an automatic binding is created between the
semantic model and a suitable gateway, which contains matching data sources for all
connections. The automatic binding fails if there's no suitable gateway or gateways.

If you're using on-premises semantic models, create the missing on-premises data
sources, and bind the semantic model to a gateway manually by using Bind To Gateway.

To discover gateways that are bindable, use Discover Gateways.

Related content
Power BI REST APIs

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Microsoft Entra permissions
Article • 06/03/2024

When you register your Microsoft Entra app, you grant it permission to access various
APIs. As your needs change, you might want to adjust these permissions. This article
shows you how.

７ Note

Microsoft Entra app permissions are only applicable for these scenarios:

Embed for your organization

Embed for your customers with the master user authentication method

Edit the permission settings on your Microsoft

Entra app
Permission changes can be made programmatically, or in the Azure portal.

Azure portal

In the Azure portal, you can view your app and make changes to its permissions.

1. Sign into the Azure portal .

2. Select your Microsoft Entra tenant by selecting your account in the upper right
corner of the page.

3. Select App registrations. If you can't see this option, search for it.

4. From the Owned applications tab, select your app. The application opens in
the Overview tab, where you can review the Application ID.

5. Select the View API permissions tab.

6. Select Add a permission.

7. To add permissions, follow these steps (note that the first step is different for
GCC apps):

a. From the Microsoft APIs tab, select Power BI service.

７ Note

For GCC apps, Select the APIs my organization uses tab, and search
for either Microsoft Power BI Government Community Cloud OR
fc4979e5-0aa5-429f-b13a-5d1365be5566.

b. Select Delegated Permissions and add or remove the specific permissions

you need.

c. When you're done, select Add permissions to save your changes.

8. To remove a permission, follow these steps:

a. Select the ellipsis (...) to the right of the permission.

b. Select Remove permission.

c. In the Remove permission pop-up window, select Yes, remove.

Related content
Considerations when generating an embed token
Capacity and SKUs in Power BI embedded analytics

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Automatically install Power BI apps
when embedding content for your
organization
Article • 06/03/2024

APPLIES TO: App owns data User owns data

To embed content from an app, the user needs access to the app that contains the
content to embed. If the app isn't installed, the embedding will fail. To make embedding
content from an app easier, you can set up automatic app installation in PowerBI.com
for your organization. Defining automatic app installation is a tenant level action and
applies to all apps.

Automatically install an app upon embedding

content
If you have access to an app that isn't installed, and try to embed app content, the
embedding will fail. To avoid this problem, allow automatic installation of the app upon
embedding content. Allowing automatic installation means if the app the user tries to
embed content from isn't installed, then the app is automatically installed for the user.
Automatic app installation results in a smoother experience for the user.

Embedding for Power BI users (User owns data)

To allow the automatic installation of apps for your users, add the Create APIs
permission to your application when you're registering your application. If you've
already registered your app, add the Create APIs permission by changing your
application's permissions.
Provide the app ID in the embed URL. To provide the app ID, the app creator must install
the app and then use one of the supported Power BI REST API calls, such as Get Reports
or Get Dashboards. The app creator must take the embed URL from the REST API
response. The app ID appears in the URL if the content is from an app. Use the embed
URL to embed content.

Secure embedding
To use automatic application installation, the app creator must install the app. Then the
app creator must go to the app on PowerBI.com, navigate to the report, and get the link.
All other users with access to the app that can use the link can embed the report.

Considerations and limitations

You can only embed reports and dashboards in this scenario.

This feature is currently not supported for app-owns data or SharePoint

embedding scenarios.
Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Best practices for faster performance in
Power BI embedded analytics
Article • 05/06/2024

This article provides recommendations for faster rendering of reports, dashboards, and
tiles in your application.

７ Note

Remember that loading time mainly depends on elements relevant to the report
and data itself, including visuals, the size of the data, and the complexity of the
queries and measures. For more information, see the Power BI optimization guide.

Update tools and SDK packages

Keep tools and SDK packages up-to-date.

Use the latest version of Power BI Desktop .

Install the latest version of the Power BI client SDK . We continuously release new
enhancements, so make sure to follow up from time to time.
Use the latest version of Tabular Editor .

Initialize embedding

Preload
Use powerbi.preload() to improve the end-user performance. The method
powerbi.preload() downloads JavaScript, css files, and other items, which are used later
to embed a report.

Call powerbi.preload() if you're not embedding the report immediately. For example, if
the embedded Power BI content doesn't appear in the home page, use
powerbi.preload() to download and cache the items that are used for embedding the

content.

Bootstrapping the iFrame

 ７ Note

Power BI client SDK version 2.9 is required to bootstrap the iFrame.

powerbi.bootstrap(element, config) allows you to start embedding before all required

parameters are available. The bootstrap API prepares and initializes the iFrame. When
using the bootstrap API, it's still required to call powerbi.embed(element, config) on the
same HTML element.

For example, one of the use cases for this feature, is to run the iFrame bootstrap and the
back-end calls for embedding, in parallel.

 Tip

Use the bootstrap API when possible to generate the iFrame before it's visible to
the end user.

​When embedding a report or other Power BI items, make sure that the embed container
is part of the DOM and that the display CSS attribute is not set to none as this can cause
unexpected behaviors. If you want to hide the embed container, consider using the
visibility CSS attribute.

Embed parameters
The powerbi.embed(element, config) method receives an element and a config
parameter. The config parameter includes fields that have performance implications.

Embed URL
Avoid generating the embed URL yourself. Instead, make sure you get the Embed URL
by calling Get reports, Get dashboards, or Get tiles API. The config parameter in the URL
is used for performance improvements.

Permissions
Provide View permissions if you don't intend to embed a report in edit mode. This way,
time isn't spent initializing components that are only used in edit mode.

Filters, bookmarks, and slicers

Usually, report visuals are saved with cached data. Reports render the cached data while
queries are executed. If filters, bookmarks, or slicers are provided, cached data isn't used
and the visuals are rendered only after the visual query has ended.

If you embed reports with the same filters, bookmarks, and slicers, save the report with
the filters, bookmarks, and slicers already applied. When you save the report this way, it
renders using the cached data that includes the filters, bookmarks, and slicers, which
improves performance.

Switching between reports

When embedding multiple reports to the same space, don't generate a new iFrame for
each report. Instead, embed the new report in the same iFrame to overwrite the
previous report. Use powerbi.embed(element, config) with a different config to embed
the new report.

７ Note

Embedding reports using embed for your customers (also known as an 'app owns
data' scenario), requires the use of an embed token with permissions to all reports
and semantic models. For more information, see the generate token API.

Multiple visuals
When embedding several visuals from the same report, don't generate a new iFrame for
each visual. Use a single iFrame to render the report with the specified visuals.

When embedding multiple visuals into a single iFrame, consider the following points:

Power BI uses iFrames to embed a report. Sometimes you might want to add more
content between the visuals (for example, text or graphics that don't come from
the report). In that case, you might need a different iFrame to render different
visuals. For best performance, try and arrange the visuals so that you use the
fewest iFrames possible. To reduce the number of iFrames, consider using the
custom-layout feature.

If you have visuals from different reports or different semantic models, consider
joining the semantic models and creating a new report so that you can include all
the visuals in the same iFrame.
 Another alternative, if you have noncontiguous regions, or data from multiple
semantic models, is to create a dashboard and pin the visuals to it. This allows you
to:
Embed the individual tiles into noncontiguous iFrames. Dashboard tiles are
lighter than reports and load faster.
Embed the entire dashboard into one iFrame. This allows you to have visuals
from different reports or semantic models in one iFrame without creating a new
report.

Keep in mind, however, that dashboard tiles aren't interactive and don't refresh
with the same frequency as visuals.

Query caching
Organizations with Power BI Premium capacity or Power BI Embedded capacity can take
advantage of query caching to speed up reports associated with a semantic model.

Learn more about query caching in Power BI.

Measure performance

Performance events
To measure embedded performance, you can use two events:

1. Loaded event: The time until the report is initialized (the Power BI logo disappears
when the load is finished).
2. Rendered event: The time until the report is fully rendered, using the actual data.
The rendered event is fired each time the report is re-rendered (for example, after
applying filters). To measure a report, make sure you do the calculations on the
first raised event.

Cached data is rendered when available but no other event is generated.

Learn more about event handling .

Performance Analyzer
To examine the performance of the report elements, you might use the Performance
Analyzer in Power BI Desktop. The Performance Analyzer allows you to see and record
logs that measure how each of your report elements performs.
Learn more about Performance Analyzer.

７ Note

Always remember to compare the embedded report performance to the

performance on powerbi.com. This might help you understand the origin of your
performance issues

Related content
Power BI optimization guide
How to troubleshoot Power BI embedded analytics issues
Power BI embedded analytics FAQ

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Power BI Embedded monitoring data
Article • 06/04/2024

When you have critical applications and business processes that rely on Azure resources,
you want to monitor those resources for their availability, performance, and operation.
This article describes the monitoring data that Microsoft Power BI Embedded generates
and how you can use the features of Azure Monitor to analyze and set alerts for this
data.

 Tip

You can also use the Microsoft Fabric Capacity Metrics app to monitor your
capacity.

Power BI Embedded Overview page

For each Power BI Embedded instance in the Azure portal, the Overview page includes
the following information:

Resource group: The resource group the Power BI Embedded instance belongs to
Status: The status of the Power BI Embedded instance
Location: The location of the Power BI Embedded instance
Subscription: The name of the Power BI Embedded instance subscription
Subscription ID: The ID of the Power BI Embedded instance subscription
Resource name: The name of the Power BI Embedded instance
SKU: The SKU that the Power BI Embedded instance uses
Resource mode: The mode of the Power BI Embedded resource

What is Azure Monitor?

Power BI Embedded creates monitoring data by using Azure Monitor. Azure Monitor is a
full-stack monitoring service in Azure that provides a complete set of features to
monitor your Azure resources. It can also monitor resources in other cloud services and
on-premises.

For more information, see Monitor Azure resources with Azure Monitor to learn about:

Azure Monitor and how it's integrated into the portal for other Azure services
The types of data collected by Azure Monitor for Azure resources
 Azure Monitor tools that are used to collect and analyze data

The following sections build on this article by describing the specific data gathered for
Power BI Embedded and provide examples for configuring data collection and analyzing
this data with Azure tools.

Monitoring data
Resources from different Azure services all generate monitoring data in the same format
so that you can use the same Azure Monitor tools to analyze them. Power BI Embedded
creates monitoring data in the same format as these other Azure resources.

For information on the metrics and logs metrics that Power BI Embedded creates, see
the Power BI Embedded monitoring data reference.

Collection and routing

Although platform metrics and the Azure Monitor activity log are collected and stored
automatically, you can route them to other locations by using diagnostic settings.
Diagnostic settings define where resource logs and metrics for a particular resource
should be sent.

Resource logs aren't collected and stored until you create at least one diagnostic setting
and route it to a location. When you create a diagnostic setting, you specify which
categories of resource logs to collect. The categories for Power BI Embedded are listed
in the Power BI Embedded monitoring data reference.

For more information about how to create and configure diagnostic settings by using
the Azure portal, Azure CLI, or Azure PowerShell, see Diagnostic settings in Azure
Monitor.

Use Azure PowerShell to enable diagnostics

To enable metrics and diagnostics logging with Azure PowerShell, use the following
Azure PowerShell commands. For information about how to use Azure PowerShell to
enable diagnostics, see Configure a Log Analytics workspace in Azure Monitor using
PowerShell.

To enable storage of diagnostics logs in a storage account, use this command:

Azure PowerShell
 Set-AzDiagnosticSetting -ResourceId [your resource id] -
StorageAccountId [your storage account id] -Enabled $true

The storage account ID is the resource ID for the storage account where you want
to send the logs.

To enable streaming of diagnostics logs to an event hub, use this command:

Azure PowerShell

Set-AzDiagnosticSetting -ResourceId [your resource id] -

ServiceBusRuleId [your service bus rule id] -Enabled $true

The Azure Service Bus rule ID is a string with this format:

Azure PowerShell

{service bus resource ID}/authorizationrules/{key name}

To enable sending diagnostics logs to a Log Analytics workspace, use this

command:

Azure PowerShell

Set-AzDiagnosticSetting -ResourceId [your resource id] -WorkspaceId

[resource id of the log analytics workspace] -Enabled $true

Get the resource ID of your Log Analytics workspace with the following command:

Azure PowerShell

(Get-AzOperationalInsightsWorkspace).ResourceId

You can combine these parameters to enable multiple output options.

The metrics and logs you can collect are discussed in the following sections.

Analyze metrics
You can analyze metrics for Power BI Embedded with metrics from other Azure services
that use Azure Monitor metrics explorer by selecting Metrics from the Azure Monitor
menu. For information about this tool, see Get started with metrics explorer.
For a list of the platform metrics collected for Power BI Embedded, see the Monitoring
Power BI Embedded data reference.

For a reference list, see resource metrics supported in Azure Monitor.

Analyze logs
Data in Azure Monitor Logs is stored in tables where each table has its own set of
unique properties.

All resource logs available through Azure Monitor share a common top-level schema
and each service has its own service-specific schema. For information about the schema
for Power BI Embedded resource logs, see the Power BI Embedded Data Reference.

The Azure Monitor activity log is an Azure platform log that provides insight into
subscription-level events. You can view it independently or route it to Azure Monitor
Logs, where you can do much more complex queries using Log Analytics.

For a list of the types of resource logs collected for Power BI Embedded, see Resource
logs.

For a list of the tables used by Azure Monitor Logs and queryable by Log Analytics, see
Supported metrics with Azure Monitor

Sample Kusto query

） Important

When you select Logs from the Power BI Embedded menu, Log Analytics opens
with the query scope set to the current Power BI Embedded resource. This means
that log queries will only include data from that resource. If you want to run a query
that includes data from another Power BI Embedded resource or data from other
Azure services, select Logs from the Azure Monitor menu. For more information,
see Log query scope and time range in Azure Monitor Log Analytics.

Here's an example of a query that completes in less than five minutes (300,000
milliseconds):

Kusto

search *
| where Type == "AzureDiagnostics"
 | where ( OperationName == "QueryEnd" )
| where toint(Duration_s) < 300000

Alerts
Azure Monitor alerts proactively notify you when important conditions are found in your
monitoring data. These alerts allow you to identify and address issues in your system
before your customers notice them. You can set alerts on metrics, logs, and the activity
log.

Related content
Learn more about monitoring data:

Monitoring Power BI Embedded data reference

Monitor Azure resources with Azure Monitor

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Embed Power BI content with service
principal and an application secret
Article • 06/03/2024

Service principal is an authentication method that can be used to let an Microsoft Entra
application access Power BI service content and APIs.

When you create a Microsoft Entra app, a service principal object is created. The service
principal object, also known simply as service principal, allows Microsoft Entra ID to
authenticate your app. After it's authenticated, the app can access Microsoft Entra
tenant resources.

To authenticate, the service principal uses the Microsoft Entra app's application ID and
one of the following:

A certificate
An application secret

This article describes service principal authentication using an application ID and an

application secret.

７ Note

We recommend that you secure your back-end services by using certificates, rather
than secret keys.

Learn more about getting access tokens from Microsoft Entra ID by using
secret keys or certificates.
To secure your solution by using a certificate, complete the instructions in this
article and then follow the steps described in Embed Power BI content with
service principal and a certificate.

Method
To use service principal and an application ID for embedded analytics, you take the
following steps. Subsequent sections describe these steps in detail.

1. Create an Microsoft Entra app.

a. Create a secret for your Microsoft Entra app.
b. Get the app's application ID and application secret.
 ７ Note

These steps are described in step 1. For more information about creating a
Microsoft Entra app, see create a Microsoft Entra app.

2. Create a Microsoft Entra security group.

3. Enable the Power BI service admin settings.

4. Add the service principal to your workspace.

5. Embed your content.

） Important

A Microsoft Entra application doesn't require you to configure any delegated

permissions or application permissions in the Azure portal when it has been
created for a service principal. When you create a Microsoft Entra application for a
service principal to access the Power BI REST API, we recommended that you avoid
adding permissions. They're never used and can cause errors that are hard to
troubleshoot.

Step 1 - Create a Microsoft Entra app

Create a Microsoft Entra app by using one of these methods:

Create the app in the Azure portal.

Create the app by using PowerShell.

Create a Microsoft Entra app in the Azure portal

1. Sign in to the Azure portal .

2. Search for and select App registrations.

3. Select New registration.

4. Fill in the required information:

Name - Enter a name for your application.

Supported account types - Select supported account types.
(Optional) Redirect URI - Enter a URI if needed.

5. Select Register.

6. After you register your app, the Application ID is available from the Overview tab.
Copy and save the Application ID for later use.
7. Select Certificates & secrets.

8. Select New client secret.

 9. In the Add a client secret window, enter a description, specify when you want the
client secret to expire, and select Add.

10. Copy and save the client secret value.

７ Note

After you leave this window, the client secret value is hidden, and you can't
view or copy it again.

Create a Microsoft Entra app by using PowerShell

The following sample PowerShell script creates a new Microsoft Entra app and a service
principal. Before you run this script:

Install the latest version of PowerShell.

Install the Microsoft Graph PowerShell SDK.

After the script runs, make a note of the following information in the script output:

The client ID of the new app

The object ID of the new service principal
The value of the service principal secret

PowerShell

# Sign in as a user who's allowed to create an app.

Connect-MgGraph -Scopes "Application.ReadWrite.All"

# Create a new Azure AD web application.

$web = @{
RedirectUris = "https://localhost:44322"
HomePageUrl = "https://localhost:44322"
}
$params = @{
DisplayName = "myAzureADApp"
Web = $($web)
}
$app = New-MgApplication @params
Write-Host "Client ID of new app: " $($app.AppId)
 # Create a service principal.
$ServicePrincipalID=@{
"AppId" = $($app.AppId)
}
$sp = New-MgServicePrincipal -BodyParameter $($ServicePrincipalId)
Write-Host "Object ID of new service principal: " $($sp.Id)

# Create a key for the service principal.

$credential = Add-MgServicePrincipalPassword -ServicePrincipalId $($sp.Id)
Write-Host "Credential of new service principal: " $($credential.SecretText)

Step 2 - Create a Microsoft Entra security group

Your service principal doesn't have access to any of your Power BI content and APIs. To
give the service principal access, create a security group in Microsoft Entra ID. Then add
the service principal you created to that security group.

７ Note

If you want to enable service principal access for the entire organization, skip this
step.

There are two ways to create a Microsoft Entra security group:

Manually (in Azure)

Use PowerShell

Create a security group manually

To create an Azure security group manually, follow the instructions in Create a basic
group and add members.

Create a security group by using PowerShell

The following sample script creates a new security group. It also adds the service
principal that you created earlier to the new security group.

Before you run the script, replace <app-client-ID> with the client ID that you
recorded earlier for your new app.
After you run the script, make a note of the object ID of the new security group,
which you can find in the script output.
 PowerShell

# Sign in as an admin.
Connect-MgGraph -Scopes "Application.ReadWrite.All"

# Get the service principal that you created earlier.

$servicePrincipal = Get-MgServicePrincipal -Filter "AppId eq '<app-client-
ID>'"

# Create an Azure AD security group.

$group = New-MgGroup -DisplayName "securitygroup1" -SecurityEnabled -
MailEnabled:$False -MailNickName "notSet"
Write-Host "Object ID of new security group: " $($group.Id)

# Add the service principal to the group.

New-MgGroupMember -GroupId $($group.Id) -DirectoryObjectId
$($servicePrincipal.Id)

Step 3 - Enable the Power BI service admin

settings
For a Microsoft Entra app to access the Power BI content and APIs, a Power BI admin
needs to enable the following settings:

Embed content in apps

Allow service principals to use Power BI APIs

In the Power BI Admin portal, go to Tenant settings, and scroll down to Developer
settings.

Enable Embed content in apps either for the entire organization or for the specific
security group you created in Microsoft Entra ID.
Enable Allow service principals to use Power BI APIs either for the entire
organization or for the specific security group you created in Microsoft Entra ID.
） Important

Service principals have access to any tenant settings they're enabled for.
Depending on your admin settings, this includes specific security groups or
the entire organization.

To restrict service principal access to specific tenant settings, allow access only
to specific security groups. Alternatively, you can create a dedicated security
group for service principals, and exclude it from the desired tenant settings.
Step 4 - Add the service principal to your
workspace
Your Microsoft Entra app can access your Power BI reports, dashboards, and semantic
models only when it has access to your Power BI workspace. You provide that access by
adding the app's service principal or its security group to your workspace as a member
or admin.

There are three ways to add a service principal or its security group to your workspace:

Manually
Use PowerShell
Use the Groups - add group user API

Add a service principal or security group manually

1. In the Power BI service, scroll to the workspace you want to enable access for.
From its More menu, select Workspace access.

2. In the Access pane, under Add admins, members, or contributors, add one of the
following:

Your service principal. The name of your service principal is the Display name
of your Microsoft Entra app, as it appears in your Microsoft Entra app's
 overview tab.
The security group that includes your service principal.

3. On the dropdown menu, select Member or Admin.

4. Select Add.

Add a service principal or security group by using

PowerShell
The following sections provide sample PowerShell scripts for adding a service principal
and a security group to a Power BI workspace as a member.

Add a service principal as a workspace member by using

PowerShell
The following script adds a service principal as a workspace member. Before you run the
script:

Replace <service-principal-object-ID> with the object ID that you recorded

earlier for your new service principal.
Replace <workspace-name> with the name of the workspace that you'd like to give
the service principal access to.

PowerShell

# Sign in to Power BI.

Login-PowerBI

# Set up the service principal ID.

$SPObjectID = "<service-principal-object-ID>"

# Get the workspace.

$pbiWorkspace = Get-PowerBIWorkspace -Filter "name eq '<workspace-name>'"

# Add the service principal to the workspace.

Add-PowerBIWorkspaceUser -Id $($pbiWorkspace.Id) -AccessRight Member -
PrincipalType App -Identifier $($SPObjectID)

Add a security group as a workspace member by using PowerShell

The following script adds a security group as a workspace member. Before you run the
script:
 Replace <security-group-object-ID> with the object ID that you recorded earlier
for your new security group.
Replace <workspace-name> with the name of the workspace that you'd like to give
the security group access to.

PowerShell

# Sign in to Power BI.

Login-PowerBI

# Set up the security group object ID.

$SGObjectID = "<security-group-object-ID>"

# Get the workspace.

$pbiWorkspace = Get-PowerBIWorkspace -Filter "name eq '<workspace-name>'"

# Add the security group to the workspace.

Add-PowerBIWorkspaceUser -Id $($pbiWorkspace.Id) -AccessRight Member -
PrincipalType Group -Identifier $($SGObjectID)

Step 5 - Embed your content

You can embed your content within a sample application, or within your own
application.

After your content is embedded, you're ready to move to production.

７ Note

To secure your content by using a certificate, follow the steps described in Embed
Power BI content with service principal and a certificate.

Considerations and limitations

My Workspace isn't supported when using service principal.
A capacity is required when moving to production.
You can't sign in to the Power BI portal by using service principal.
Power BI admin rights are required to enable service principal in developer settings
within the Power BI Admin portal.
Embed for your organization applications can't use service principal.
Dataflows management isn't supported.
 Service principal only supports some read-only admin APIs. To enable service
principal support for read-only admin APIs, you have to enable the Power BI
service admin settings in your tenant. For more information, see Enable service
principal authentication for read-only admin APIs.
When you use service principal with an Azure Analysis Services data source, the
service principal itself must have Azure Analysis Services instance permissions.
Using a security group that contains the service principal for this purpose doesn't
work.

Related content
Register an app
Power BI Embedded for your customers
Application and service principal objects in Microsoft Entra ID

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Embed Power BI content with service
principal and a certificate
Article • 04/10/2024

Certificate-based authentication enables you to be authenticated by Microsoft Entra ID

with a client certificate. The client certificate can be on a Windows, Android, or iOS
device, or the client certificate can be kept in an Azure Key Vault.

Using this method of authentication allows managing certificates from a central place
using the certificate authority (CA) for rotation or revocation.

You can learn more about certificates in Microsoft Entra ID in the Client credential
flows GitHub page.

Method
1. Embed your content with service principal.

2. Create a certificate.

3. Set up certificate authentication.

4. Get the certificate from Azure Key Vault.

5. Authenticate using service principal and a certificate.

Step 1 - Embed your content with service

principal
To embed your content with a service principal, follow the instructions in Embed Power
BI content with service principal and an application secret.

７ Note

If you already have content that's embedded using a service principal, skip this step
and advance to step 2.

Step 2 - Create a certificate

You can procure a certificate from a trusted Certificate Authority, or generate a
certificate yourself.

This section describes creating a certificate using Azure Key Vault, and downloading the
.cer file, which contains the public key.

1. Log into Microsoft Azure .

2. Search for and select the Key vaults link.

3. Select the key vault you want to add a certificate to.

4. Select Certificates.
5. Select Generate/Import.

6. Configure the Create a certificate fields as follows:

 Method of Certificate Creation - General

Certificate Name - Enter a name for your certificate

Type of Certificate Authority (CA) - Self-signed certificate

Subject - An X.500 distinguished name

DNS Names - 0 DNS names

Validity Period (in months) - Enter the certificate's validity duration

Content Type - PKCS #12

Lifetime Action Type - Automatically renew at a given percentage lifetime

Percentage Lifetime - 80

Advanced Policy Configuration - Not configured

7. Select Create. The newly created certificate is disabled by default. It can take up to
five minutes to become enabled.

8. Select the certificate you created.

9. Select Download in CER format. The downloaded file contains the public key.

Step 3 - Set up certificate authentication

1. In your Microsoft Entra application, select the Certificates & secrets tab.
 2. Select Upload certificate and upload the .cer file you created and downloaded in
step 2 of this tutorial. The .cer file contains the public key.

Step 4 - Get the certificate from Azure Key

Vault
Use Managed Service Identity (MSI) to get the certificate from Azure Key Vault. This
process involves getting the .pfx certificate that contains both the public and private
keys.

Refer to the code example for reading the certificate from Azure Key Vault. If you want
to use Visual Studio, refer to Configure Visual Studio to use MSI.

C#

private X509Certificate2 ReadCertificateFromVault(string certName)

{
var serviceTokenProvider = new AzureServiceTokenProvider();
var keyVaultClient = new KeyVaultClient(new
KeyVaultClient.AuthenticationCallback(serviceTokenProvider.KeyVaultTokenCall
back));
CertificateBundle certificate = null;
SecretBundle secret = null;

certificate =
keyVaultClient.GetCertificateAsync($"https://{KeyVaultName}.vault.azure.net/
", certName).Result;
secret =
keyVaultClient.GetSecretAsync(certificate.SecretIdentifier.Identifier).Resul
t;
 return new X509Certificate2(Convert.FromBase64String(secret.Value));
}

Step 5 - Authenticate using service principal

and a certificate
You can authenticate your app that uses a service principal and a certificate that's stored
in Azure Key Vault by connecting to Azure Key Vault.

To connect and read the certificate from Azure Key Vault, refer to the following code
sample.

７ Note

If you already have a certificate created by your organization, upload the .pfx file to
Azure Key Vault.

C#

// Preparing needed variables

var Scope = "https://analysis.windows.net/powerbi/api/.default"
var ApplicationId = "{YourApplicationId}"
var tenantSpecificURL = "https://login.microsoftonline.com/{YourTenantId}/"
X509Certificate2 certificate = ReadCertificateFromVault(CertificateName);

// Authenticating with a SP and a certificate

public async Task<AuthenticationResult> DoAuthentication(){
IConfidentialClientApplication clientApp = null;
clientApp = ConfidentialClientApplicationBuilder.Create(ApplicationId)

.WithCertificate(certificate)

.WithAuthority(tenantSpecificURL)
.Build();
return await clientApp.AcquireTokenForClient(Scope).ExecuteAsync();
}

Configure Visual Studio to use MSI

When you create an embedded solution, it might be useful to configure Visual Studio to
use Managed Service Identity (MSI). MSI is a feature that enables you to manage your
Microsoft Entra identity. Once configured, it will let Visual Studio authenticate against
your Azure Key Vault.

７ Note

The user that signs into Visual Studio requires Azure Key Vault permissions to get
the certificate.

1. Open your project in Visual Studio.

2. Select Tools > Options.

3. Search for and select Account Selection.

 4. Add the account that has access to your Azure Key Vault.

Related content
Set up Power BI Embedded
Tutorial: Embed Power BI content using a sample embed for your customers'
application
Application and service principal objects in Microsoft Entra ID
Embed a report on an on-premises SQL Server Analysis Services (SSAS)

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Tutorial: Embed Power BI content using
a sample embed for your customers'
application
Article • 05/13/2024

APPLIES TO: App owns data User owns data

Embedded analytics and Power BI Embedded (the Azure offer) allow you to embed
Power BI content such as reports, dashboards, and tiles, into your application.

In this tutorial, you learn how to:

＂ Set up your embedded environment.

＂ Configure an embed for your customers (also known as app owns data) sample
application.

To use your application, your users don't need to sign in to Power BI or have a Power BI
license.

We recommend using the embed for your customers method to embed your Power BI
content, if you're an independent software vendor (ISV) or a developer, who wants to
create applications for third parties.

） Important

If you are embedding content for a national/regional cloud, the first few steps of
this tutorial are different. See Embed content for national/regional clouds for
details.

Code sample specifications

This tutorial includes instructions for configuring an embed for your customers sample
application in one of the following frameworks:

.NET Framework
.NET Core
Java
Node JS
Python
The code samples support the following browsers:

Microsoft Edge
Google Chrome
Mozilla Firefox

Prerequisites
Before you start this tutorial, verify that you have the following the Power BI and code
dependencies:

Power BI dependencies

Your own Microsoft Entra tenant.

To authenticate your app against Power BI, you need one of the following:

Service principal - a Microsoft Entra service principal object that allows

Microsoft Entra ID to authenticate your app.

Power BI Pro license - This is your master user and your app uses it to
authenticate to Power BI.

A Power BI Premium Per User (PPU) license - This is your master user and
your app uses it to authenticate to Power BI.

７ Note

To move to production you'll need a capacity.

Code dependencies

.NET Core

.NET Core 3.1 SDK (or higher)

An integrated development environment (IDE). We recommend using one of

the following environments:

Visual Studio

Visual Studio Code

Method
To create an embed for your customers sample app, follow these steps:

1. Select your authentication method.

2. Register a Microsoft Entra application.

3. Create a Power BI workspace.

4. Create and publish a Power BI report.

5. Get the embedding parameter values.

6. Service principal API access

7. Enable workspace access.

8. Embed your content.

Step 1 - Select your authentication method

Your embedded solution varies depending on the authentication method you select.
Therefore, it's important to understand the differences between the authentication
methods, and decide which one best suits your solution.

The following table describes a few key differences between the service principal and
master user authentication methods.

ﾉ Expand table

Consideration Service principal Master user

Mechanism Your Microsoft Entra app's Your Microsoft Entra app uses the
service principal object allows credentials (username and password) of a
Microsoft Entra ID to Power BI user, to authenticate against
authenticate your embedded Power BI.
solution app against Power BI.

Security Service principal is the This authentication method isn't as secure

Microsoft Entra ID as a service principal. You have to be
recommended authorization vigilant with the master user credentials
method. If you're using a (username and password). For example,
service principal, you can don't expose them in your embedding
authenticate using either an application, and change the password
application secret or a frequently.
certificate.
 Consideration Service principal Master user

This tutorial only describes

using service principal with an
application secret. To embed
using a service principal and a
certificate, refer to the service
principal with a certificate
article.

Microsoft Entra Not required. Your master user or an administrator has to

ID delegated grant consent for your app to access Power
permissions BI REST API permissions (also known as
scopes). For example, Report.ReadWrite.All.

Power BI service You can't access Power BI You can access Power BI service with your
access service with a service principal. master user credentials.

License Doesn't require a Pro license. Requires a Power BI Pro or Premium Per
You can use content from any User (PPU) license.
workspace that you're a
member or an admin of.

Step 2 - Register a Microsoft Entra application

Registering your application with Microsoft Entra ID allows you to:

＂ Establish an identity for your app

＂ Let your app access the Power BI REST APIs
＂ If you're using a master user - Specify your app's Power BI REST permissions

To register your application with Microsoft Entra ID, follow the instructions in Register
your application.

７ Note

Before registering your application, you'll need to decide which authentication

method to use, service principal or master user.

Step 3 - Create a Power BI workspace

Power BI keeps your reports, dashboards, and tiles in a workspace. To embed these
items, you'll need to create them and upload them into a workspace.
  Tip

If you already have a workspace, you can skip this step.

To create a workspace, do the following:

1. Sign in to Power BI.

2. Select Workspaces.

3. Select Create a workspace.

4. Name your workspace and select Save.

Step 4 - Create and publish a Power BI report

Your next step is to create a report and upload it to your workspace. You can create your
own report using Power BI Desktop, and then publish it to your workspace. Or, you can
upload a sample report to your workspace.

 Tip

If you already have a workspace with a report, you can skip this step.

To download a sample report and publish it to your workspace, follow these steps:

1. Open the GitHub Power BI Desktop samples folder.

2. Select Code and then select Download zip.

 3. Extract the downloaded ZIP and navigate to the Samples Reports folder.

4. Select a report to embed, and publish it to your workspace.

Step 5 - Get the embedding parameter values

To embed your content, you need to obtain certain parameter values. The following
table shows the required values, and indicates if they're applicable to the service
principal authentication method, the master user authentication method, or both.

Before you embed your content, make sure you have all the values listed below. Some
of the values might differ, depending on the authentication method you're using.

ﾉ Expand table

Parameter Service principal Master user

Client ID

Workspace ID

Report ID

Client secret

Tenant ID required only for Node JS

Power BI username
 Parameter Service principal Master user

Power BI password

Client ID

 Tip

Applies to: Service principal Master user

To get the client ID GUID (also know as application ID), follow these steps:

1. Log into Microsoft Azure .

2. Search for App registrations and select the App registrations link.

3. Select the Microsoft Entra app you're using for embedding your Power BI content.

4. From the Overview section, copy the Application (client) ID GUID.

Workspace ID

 Tip

Applies to: Service principal Master user

To get the workspace ID GUID, follow these steps:

1. Sign in to Power BI service.

2. Open the report you want to embed.

3. Copy the GUID from the URL. The GUID is the number between /groups/ and
/reports/.

Alternatively, you can find the workspace ID in the Admin portal settings by selecting
Details next to the workspace name.
Report ID

 Tip

Applies to: Service principal Master user

To get the report ID GUID, follow these steps:

1. Sign in to Power BI service.

2. Open the report you want to embed.

3. Copy the GUID from the URL. The GUID is the number between /reports/ and
/ReportSection.

Client secret

 Tip

Applies to: Service principal Master user

To get the client secret, follow these steps:

 1. Log into Microsoft Azure .

2. Search for App registrations and select the App registrations link.

3. Select the Microsoft Entra app you're using for embedding your Power BI content.

4. Under Manage, select Certificates & secrets.

5. Under Client secrets, select New client secret.

6. In the Add a client secret pop-up window, provide a description for your
application secret, select when the application secret expires, and select Add.

7. From the Client secrets section, copy the string in the Value column of the newly
created application secret. The client secret value is your client ID.

７ Note

Make sure you copy the client secret value when it first appears. After navigating
away from this page, the client secret will be hidden and you'll not be able to
retrieve its value.

Tenant ID

 Tip

Applies to: Service principal Master user

To get the tenant ID GUID, follow these steps:

1. Log into Microsoft Azure .

2. Search for App registrations and select the App registrations link.

3. Select the Microsoft Entra app you're using for embedding your Power BI content.

4. From the Overview section, copy the Directory (tenant) ID GUID.

Power BI username and password

 Tip
 Applies to: Service principal Master user

Obtain the username and password of the Power BI user you're using as your master
user. This is the same user you used to create a workspace and upload a report to, in
Power BI service.

Step 6 - Service principal API access

 Tip

Applies to: Service principal Master user

This step is only relevant if you're using the service principal authentication method.
If you're using a master user, skip this step and continue with Step 7 - Enable
workspace access.

For a Microsoft Entra app to be able to access the Power BI content and APIs, a Power BI
admin needs to enable service principal access in the Power BI admin portal. If you're
not the admin of your tenant, get the tenant's admin to enable the Tenant settings for
you.

1. In Power BI service, select Settings > Settings > Admin portal.

 2. Select Tenant settings and then scroll down to the Developer settings section.

3. Expand Service principals can use Fabric APIs, and enable this option.

７ Note

When using a service principal, it's recommended to limit its access to the tenant
settings using a security group. To learn more about this feature, see these sections
in the service principal article:

Create a Microsoft Entra security group

Enable the Power BI service admin settings

Step 7 - Enable workspace access

To enable your Microsoft Entra app access objects such as reports, dashboards and
semantic models in the Power BI service, add the service principal or master user, as a
member or admin to your workspace.

1. Sign in to Power BI service.

 2. Scroll to the workspace you want to enable access for, and from the More menu,
select Workspace access.

3. In the Access pane, depending on which authentication method you're using, copy
the service principal or master user to the Enter email address text box.

７ Note

If you're using a service principal, its name is the name you gave your
Microsoft Entra app.

4. Select Add.

Step 8 - Embed your content

The Power BI embedded sample application allows you to create an embed for your
customers Power BI app.

Follow these steps to modify the embed for your customers sample application, to
embed your Power BI report.

1. Open the Power BI developer samples folder.

2. Select Code and then select Download zip.

3. Extract the downloaded ZIP and navigate to the PowerBI-Developer-Samples-
master folder.

4. Depending on the language you want your app to use, open one of these folders:

.NET Core
.NET Framework
Java
Node JS
Python

７ Note

The embed for your customers sample applications only support the
frameworks listed above. The React sample application only supports the
embed for your organization solution.

5. Open the Embed for your customers folder.

.NET Core

6. Open the embed for your customers sample app using one of these methods:

If you're using Visual Studio , open the AppOwnsData.sln file.

If you're using Visual Studio Code , open the AppOwnsData folder.

 7. Open appsettings.json.

8. Depending on your authentication method, fill in the following parameter

values:

ﾉ Expand table

Parameter Service principal Master user

AuthenticationMode ServicePrincipal MasterUser

ClientId Your Microsoft Entra app client Your Microsoft Entra app
ID client ID

TenantId Your Microsoft Entra tenant ID N/A

PbiUsername N/A Your master user username,

see Power BI username and
password

PbiPassword N/A Your master user password,

see Power BI username and
password

ClientSecret Your Microsoft Entra ID client N/A

secret

WorkspaceId The ID of the workspace with The ID of the workspace with

your embedded report, see your embedded report, see
Workspace ID Workspace ID

ReportId The ID of the report you're The ID of the report you're

embedding, see Report ID embedding, see Report ID

9. Run the project by selecting the appropriate option:

If you're using Visual Studio, select IIS Express (play).

If you're using Visual Studio Code, select Run > Start Debugging.

Developing your application

After configuring and running the embed for your customers sample application, you can
start developing your own application.
Try out the Power BI embedded analytics playground to get started developing and to
keep up with all the new Power BI Embedded features and updates.

When you're ready, review the move to production requirements. You'll also need a
capacity, and should review the capacity planning article to establish which SKU best
suits your needs.

） Important

If you used free embed trial tokens for development, you must buy a capacity for
production. Until a capacity is purchased, the Free trial version banner will continue
to appear at the top of the embedded report.

Related content
Move to production
Embed for your organization
Embed paginated reports

More questions? Ask the Power BI Community .

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Tutorial: Embed Power BI content using
a sample embed for your organization
application
Article • 01/30/2024

Power BI embedded analytics allows you to embed Power BI content, such as reports,
dashboards and tiles, into your application.

In this tutorial, you'll learn how to:

＂ Set up your embedded environment.

＂ Configure an embed for your organization (also known as user owns data) sample
application.

To use your application, your users will need to sign in to Power BI.

The embed for your organization solution is typically used by enterprises and large
organizations, and is intended for internal users.

） Important

If you are embedding content for a national/regional cloud, the first few steps of
this tutorial are different. See Embed content for national/regional clouds for
details.

Code sample specifications

This tutorial includes instructions for configuring an embed for your organization sample
application in one of the following frameworks:

.NET Framework
.NET Core
React TypeScript

７ Note

The .NET Core and the .NET Framework samples allow the end user to view any
Power BI dashboard, report or tile they have access to in the Power BI service. The
 React TypeScript sample lets you embed only one report that your end user already
has access to in the Power BI service.

The code samples support the following browsers:

Microsoft Edge
Google Chrome
Mozilla Firefox

Prerequisites
Before you start this tutorial, verify that you have both the following Power BI and code
dependencies:

Power BI dependencies

Your own Microsoft Entra tenant.

One of the following licenses:

Power BI Pro

Premium Per User (PPU)

７ Note

To move to production you'll need one of the following configurations:

All users with Pro licenses.
All users with PPU licenses.
A SKU that's equivalent or higher to a F64 SKU. This configuration
allows all users to have free licenses.

Code dependencies

.NET Core

.NET Core 3.1 SDK (or higher)

An integrated development environment (IDE). We recommend using one

of the following IDEs:

Visual Studio
 Visual Studio Code

Method
To create an embed for your organization sample app, follow these steps:

1. Register a Microsoft Entra application.

2. Create a Power BI workspace.

3. Create and publish a Power BI report.

4. Get the embedding parameter values.

5. Embed your content.

Step 1 - Register a Microsoft Entra application

Registering your application with Microsoft Entra ID allows you to establish an identity
for your app.

To register your application with Microsoft Entra ID, follow the instructions in Register
your application.

Step 2 - Create a Power BI workspace

Power BI keeps your reports, dashboards, and tiles in a workspace. To embed these
items, you'll need to create them and upload them into a workspace.

 Tip

If you already have a workspace, you can skip this step.

To create a workspace, do the following:

1. Sign in to Power BI.

2. Select Workspaces.

3. Select Create a workspace.

4. Name your workspace and select Save.

Step 3 - Create and publish a Power BI report
Your next step is to create a report and upload it to your workspace. You can create your
own report using Power BI Desktop, and then publish it to your workspace. Or, you can
upload a sample report to your workspace.

 Tip

If you already have a workspace with a report, you can skip this step.

To download a sample report and publish it to your workspace, follow these steps:

1. Open the GitHub Power BI Desktop samples folder.

2. Select Code and then select Download zip.

3. Extract the downloaded ZIP and navigate to the Samples Reports folder.

4. Select a report to embed, and publish it to your workspace.

Step 4 - Get the embedding parameter values

To embed your content, you'll need to obtain a few parameter values. The parameter
values depend on the language of the sample application you want to use. The table
below lists which parameter values are required for each sample.
 ﾉ Expand table

Parameter .NET Core .NET Framework React TypeScript

Client ID

Client secret

Workspace ID

Report ID

Client ID

 Tip

Applies to: .NET Core .NET Framework React TypeScript

To get the client ID GUID (also know as application ID), follow these steps:

1. Log into Microsoft Azure .

2. Search for App registrations and select the App registrations link.

3. Select the Microsoft Entra app you're using for embedding your Power BI content.

4. From the Overview section, copy the Application (client) ID GUID.

Client secret

 Tip

Applies to: .NET Core .NET Framework React TypeScript

To get the client secret, follow these steps:

1. Log into Microsoft Azure .

2. Search for App registrations and select the App registrations link.

3. Select the Microsoft Entra app you're using for embedding your Power BI content.

4. Under Manage, select Certificates & secrets.

 5. Under Client secrets, select New client secret.

6. In the Add a client secret pop-up window, provide a description for your
application secret, select when the application secret expires, and select Add.

7. From the Client secrets section, copy the string in the Value column of the newly
created application secret. The client secret value is your client ID.

７ Note

Make sure you copy the client secret value when it first appears. After navigating
away from this page, the client secret will be hidden and you'll not be able to
retrieve its value.

Workspace ID

 Tip

Applies to: .NET Core .NET Framework React TypeScript

To get the workspace ID GUID, follow these steps:

1. Sign in to Power BI service.

2. Open the report you want to embed.

3. Copy the GUID from the URL. The GUID is the number between /groups/ and
/reports/.

Report ID

 Tip

Applies to: .NET Core .NET Framework ReactTypeScript

To get the report ID GUID, follow these steps:

1. Sign in to Power BI service.

 2. Open the report you want to embed.

3. Copy the GUID from the URL. The GUID is the number between /reports/ and
/ReportSection.

Step 5 - Embed your content

The Power BI embedded sample application allows you to create an embed for your
organization Power BI app.

Follow these steps to modify the embed for your organization sample application, to
embed your Power BI report.

1. Open the Power BI developer samples folder.

2. Select Code and then select Download zip.

3. Extract the downloaded ZIP and navigate to the PowerBI-Developer-Samples-

master folder.

4. Open one of the following folders depending on the language you want your
application to use:

.NET Core
.NET Framework
React-TS
 ７ Note

The embed for your organization sample applications only support the
previously listed frameworks. The Java, Node JS and Python sample
applications, only support the embed for your customers solution.

.NET Core

Configure your Microsoft Entra app

1. Sign into the Azure portal .

2. Select App registrations. If you can't see this option, search for it.

3. Open the Microsoft Entra application you created in Step 1 - Register a

Microsoft Entra application.

4. From the Manage menu, select Authentication.

5. In Platform configurations, open your Web platform and in the Redirect URIs
section, add https://localhost:5000/signin-oidc .

７ Note

If you don't have a Web platform, select Add a platform and in the
Configure platforms window, choose Web.

6. Save your changes.

 Configure the sample embedding app
1. Open the Embed for your organization folder.

2. Open the embed for your organization sample app using one of these
methods:

If you're using Visual Studio , open the UserOwnsData.sln file.

If you're using Visual Studio Code , open the UserOwnsData folder.

3. Open appsettings.json and fill in the following parameter values:

ClientId - Use the client ID GUID

ClientSecret - Use the client secret

Run the sample app

1. Run the project by selecting the appropriate option:

If you're using Visual Studio, select IIS Express (play).

If you're using Visual Studio Code, select Run > Start Debugging.

2. Sign into the embedding sample application.

７ Note

During your first sign in, you'll be prompted to allow Microsoft Entra
permissions for the app.

3. When the embedding sample application loads, select the Power BI content
you want to embed and then select Embed.

Develop your application

After configuring and running the embed for your customers sample application, you can
start developing your own application.

Update user permissions

Users need permission to access the Power BI folder the report is in. When you grant a
user permission to access a folder, the change usually takes effect only after the user
logs in to the Power BI Portal. For the new permissions to take effect immediately, in the
Embedded scenario, make an explicit call to the RefreshUser Permissions REST API at
startup. This API call will refresh the permissions and avoid authorization failures for
users with newly granted permissions.

Related content
Tutorial: Embed Power BI content using a sample embed for your customers'
application

Embed paginated reports

Ask the Power BI Community

Tutorial: Embed Power BI content into
your application for national/regional
clouds
Article • 03/07/2024

Learn how to embed analytical content within your business process applications for the
national/regional cloud. Use the Power BI .NET SDK with the Power BI JavaScript API to
embed a report, dashboard, or tile, into your web applications.

Power BI supports the following national/regional clouds:

U.S. Government Community Cloud (GCC)

U.S. Government Community Cloud High (GCC High)

U.S. Military Contractors (DoDCON)

U.S. Military (DoD)

Power BI for China cloud

To get started with this walkthrough, you need a Power BI account. If you don't have an
account set up, depending on the type of government or country/region, you can
choose the right national/regional cloud for you. Sign up for a U. S. government Power
BI account, or a Power BI for China cloud account .
 ７ Note

Are you looking to embed a dashboard for your organization instead? See
Integrate a dashboard into an app for your organization.

To integrate a dashboard into a web app, use the Power BI API and a Microsoft Entra
authorization access token to get a dashboard. Load the dashboard using an embed
token. The Power BI API provides programmatic access to specific Power BI resources.
For more information, see Power BI REST API, Power BI .NET SDK, and the Power BI
JavaScript API .

Download the sample

This article shows the code for the App Owns Data sample on GitHub. To follow along
with this walkthrough, download the sample. We're using the .NET Framework/Embed for
your customers directory.

） Important

You can only embed Power BI content from a Government Community Cloud (GCC)
with a Microsoft 365 SKU. Other national/regional cloud customers can use
Microsoft 365 or Azure SKUs.
Government Community Cloud (GCC):

1. In the Web.config file, update applicationId (Native app applicationId ),

workspaceId , the username (your master user), and password.

2. Next, add the GCC parameters as follows.

XML

<add key="authorityUrl"
value="https://login.microsoftonline.com/organizations/" />
<add key="scopeBase"
value="https://analysis.usgovcloudapi.net/powerbi/api/.default" />
<add key="urlPowerBiServiceApiRoot"
value="https://api.powerbigov.us/" />

Military Contractors (DoDCON):

1. In the Web.config file, update applicationId (Native app applicationId ),

workspaceId , the username (your master user), and password.

2. Next, add the DoDCON parameters as follows.

XML

<add key="authorityUrl"
value="https://login.microsoftonline.us/organizations/" />
<add key="scopeBase"
value="https://high.analysis.usgovcloudapi.net/powerbi/api/.defaul
t" />
<add key="urlPowerBiServiceApiRoot"
value="https://api.high.powerbigov.us/" />

Military (DoD):
 1. In the Web.config file, update applicationId (Native app applicationId ),
workspaceId , the username (your master user), and password.

2. Next, add the DoDCON parameters as follows.

XML

<add key="authorityUrl"
value="https://login.microsoftonline.us/organizations/" />
<add key="scopeBase"
value="https://mil.analysis.usgovcloudapi.net/powerbi/api/.default
" />
<add key="urlPowerBiServiceApiRoot"
value="https://api.mil.powerbigov.us/" />

Power BI for China cloud parameters

1. In the Web.config file, update applicationId (Native app applicationId ),

workspaceId , the username (your master user), and password.

2. Next, add the Power BI for China cloud parameters as follows.

XML

<add key="authorityUrl"
value="https://login.chinacloudapi.cn/organizations/" />
<add key="scopeBase"
value="https://analysis.chinacloudapi.cn/powerbi/api/.default" />
<add key="urlPowerBiServiceApiRoot"
value="https://api.powerbi.cn/" />

Step 1 - register an app in Microsoft Entra ID

Register your application with Microsoft Entra ID to make REST API calls. For more
information, see Register a Microsoft Entra app to embed Power BI content. Since there
are different national/regional cloud affiliations, there are distinct URLs to register your
application.

Government Community Cloud (GCC) - https://app.powerbigov.us/apps

Military Contractors (DoDCON) - https://app.high.powerbigov.us/apps

Military (DoD) - https://app.mil.powerbigov.us/apps

Power BI for China cloud - https://app.powerbi.cn/apps

If you downloaded the Embedding for your customer sample , you would use the
applicationId you get, so that the sample can authenticate to Microsoft Entra ID. To

configure the sample, change the applicationId in the web.config file.

Step 2 - get an access token from Microsoft

Entra ID
Within your application, you need to get an access token, from Microsoft Entra ID,
before you can make calls to the Power BI REST API. For more information, see
Authenticate users and get a Microsoft Entra access token for your Power BI app. Since
there are different national/regional cloud affiliations, there are distinct URLs to get an
access token for your application.

Government Community Cloud (GCC) - https://login.microsoftonline.com

Military Contractors (DoDCON) - https://login.microsoftonline.us

Military (DoD) - https://login.microsoftonline.us

Power BI for China cloud - https://login.chinacloudapi.cn

You can see examples of these access tokens within each content item task in the
Controllers\HomeController.cs file.

Step 3 - embed content

Now that you have an access token, you can continue embedding as you would on any
other platform.

Embed content for customers

Embed content for your organization

Related content
Embedding for your customers sample

Power BI JavaScript API

More questions? Ask the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Tutorial: Embed a Power BI report in an
application for your customers
Article • 06/03/2024

In this tutorial, you learn how to embed a Power BI report in a .NET 5.0 application, as
part of the embed-for-your-customers (also known as an app-owns-data) solution. In an
embed-for-your-customers solution, your app users don't need to sign in to Power BI or
have a Power BI license.

In this tutorial, you learn how to embed:

＂ A Power BI report.
＂ In an embed-for-your-customers app.
＂ By using a service principal.
＂ By using .NET 5.0.
＂ With the Microsoft.Identity.Web library (this library is also supported in .NET Core).

７ Note

The full solution used in this tutorial is available from the DOTNET5-
AppOwnsData-Tutorial GitHub repository.

Prerequisites
A Power BI Pro or Premium Per User (PPU) license

A Power BI workspace with a report

Your own Microsoft Entra tenant

An Microsoft Entra app

A .NET Core 5 model view controller (MVC) app

.NET Core 5 SDK or later

An integrated development environment (IDE). We recommend one of the

following IDEs:

Visual Studio .

Visual Studio Code with the C# extension

Resources
In this tutorial, you use:

Power BI REST Reports API, to embed the URL and retrieve the embed token.

Microsoft Identity Web authentication library.

Power BI embedded analytics Client APIs, to embed the report.

Method
To embed Power BI content in an embed-for-your-customers solution, follow these
steps:

1. Configure your Microsoft Entra app and service principal.

2. Get the embedding parameter values.

3. Add the required NuGet packages.

4. Enable server side authentication.

5. Build your app's client side.

6. Run your application.

Step 1 - Configure your Microsoft Entra app

and service principal
In this tutorial, you use a service principal to authenticate your web app against
Microsoft Entra ID. You also need a Microsoft Entra app, which makes it possible to
generate an Microsoft Entra token. By using the Microsoft Entra token, your web app
can call Power BI REST APIs and embed Power BI items, such as reports, dashboards, and
tiles.

Follow the service principal instructions to create a Microsoft Entra app and enable the
app's service principal to work with your Power BI content.

Step 2 - Get the embedding parameter values

To embed your report, you need the following values:
 Domain
Tenant ID
Client ID
Client secret
Workspace ID
Report ID

Domain and tenant ID

If you don't know your domain or tenant ID, see Find the Microsoft Entra tenant ID and
primary domain name.

７ Note

To embed content for a user on a different tenant (guest user), you need to adjust
the authorityUri parameter.

Client ID
To get the client ID GUID (also know as application ID), follow these steps:

1. Log into Microsoft Azure .

2. Search for App registrations and select the App registrations link.

3. Select the Microsoft Entra app you're using for embedding your Power BI content.

4. From the Overview section, copy the Application (client) ID GUID.

Client secret
To get the client secret, follow these steps:

1. Log into Microsoft Azure .

2. Search for App registrations and select the App registrations link.

3. Select the Microsoft Entra app you're using for embedding your Power BI content.

4. Under Manage, select Certificates & secrets.

5. Under Client secrets, select New client secret.

 6. In the Add a client secret pop-up window, provide a description for your
application secret, select when the application secret expires, and select Add.

7. From the Client secrets section, copy the string in the Value column of the newly
created application secret. The client secret value is your client ID.

７ Note

Make sure you copy the client secret value when it first appears. After navigating
away from this page, the client secret will be hidden and you'll not be able to
retrieve its value.

Workspace ID
To get the workspace ID GUID, follow these steps:

1. Sign in to Power BI service.

2. Open the report you want to embed.

3. Copy the GUID from the URL. The GUID is the number between /groups/ and
/reports/.

７ Note

To get the workspace ID programmatically, use the Get Groups API.

Report ID
To get the report ID GUID, follow these steps:

1. Sign in to Power BI service.

2. Open the report you want to embed.

3. Copy the GUID from the URL. The GUID is the number between /reports/ and
/ReportSection.
 ７ Note

To get the report ID programmatically, use the Get Reports In Group API.

Step 3 - Add the required NuGet packages

Before you can start, you need to add the Microsoft.Identity.Web , and
Microsoft.PowerBI.Api NuGet packages to your app.

Add the required NuGet packages to your app:

In VS Code, open a terminal and enter the following code.

In Visual Studio, navigate to Tools > NuGet Package Manager > Package
Manager Console and type in the following code.

PowerShell

dotnet add package Microsoft.Identity.Web

dotnet add package Microsoft.Identity.Web.UI
dotnet add package Microsoft.PowerBI.Api

Step 4 - Enable server-side authentication

Turn on server-side authentication in your app by creating or modifying the files in the
following table.

ﾉ Expand table

File Use

Startup.cs Initialize the Microsoft.Identity.Web authentication service

appsettings.json Configure authentication details

PowerBiServiceApi.cs Get the Microsoft Entra token and embedding metadata

HomeController.cs Pass embedding data as a model to the view

Configure your startup file to support

Microsoft.Identity.Web
Modify the code in Startup.cs to properly initialize the authentication service provided
by Microsoft.Identity.Web .

Add the following code to your app's Startup.cs file.

７ Note

The code in ConfigureServices accomplishes several important things:

1. The call to AddMicrosoftWebAppCallsWebApi configures the Microsoft

Authentication Library to acquire access tokens (Microsoft Entra tokens).
2. The call to AddInMemoryTokenCaches configures a token cache that the
Microsoft Authentication Library uses to cache access tokens and refresh
tokens behind the scenes.
3. The call to services.AddScoped(typeof(PowerBiServiceApi)) configures the
PowerBiServiceApi class as a service class that can be added to other classes

by using dependency injection.

C#

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.HttpsPolicy;
using Microsoft.AspNetCore.Mvc.Authorization;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using AppOwnsData.Services;

namespace AppOwnsData
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
 public IConfiguration Configuration { get; }

// This method gets called by the runtime. Use this method to add
services to the container.
public void ConfigureServices(IServiceCollection services) {

services.AddMicrosoftIdentityWebAppAuthentication(Configuration)
.EnableTokenAcquisitionToCallDownstreamApi()
.AddInMemoryTokenCaches();

services.AddScoped(typeof(PowerBiServiceApi));

services.AddControllersWithViews(options => {
var policy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
options.Filters.Add(new AuthorizeFilter(policy));
});
services.AddRazorPages()
.AddMicrosoftIdentityUI();
}

// This method gets called by the runtime. Use this method to

configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment
env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
// The default HSTS value is 30 days. You might want to
change this for production scenarios. See https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
endpoints.MapRazorPages();
});
}
 }
}

Create an authentication details file

In this tutorial, the appsettings.json file contains sensitive information, such as client ID
and client secret. For security reasons, we don't recommend that you keep this
information in the settings file. When embedding in your application, consider a more
secure tool, such as Azure Key Vault, to secure sensitive information.

1. In your project, create a new file and name it appsettings.json.

2. Add the following code to appsettings.json:

JSON

{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "yourtenant.onMicrosoft.com",
"TenantId": "",
"ClientId": "",
"ClientSecret": "",
"CallbackPath": "/signin-oidc",
"SignedOutCallbackPath": "/signout-callback-oidc"
},
"PowerBi": {
"ServiceRootUrl": "https://api.powerbi.com/"
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}

3. Fill in the embedding parameter values obtained from Step 2 - Get the embedding
parameter values.

Domain - Domain and tenant ID

TenantId - Domain and tenant ID

ClientId - Client ID

ClientSecret - Client secret

 ７ Note

In the preceding code, the PowerBi:ServiceRootUrl parameter is added as a custom

configuration value to track the base URL to the Power BI service. When you
program against the Power BI service in the Microsoft public cloud, the URL is
https://api.powerbi.com/ . However, the root URL for the Power BI service is

different in other clouds, such as the government cloud. Therefore, the custom
configuration value is stored as a project configuration value, so you can change it
as needed.

Get the Microsoft Entra access token and call the Power
BI service
In order to embed Power BI content like reports and dashboards, your app needs to get
an Microsoft Entra token. To get the token, you need a configuration object.

The code in this section uses the .NET Core dependency injection pattern. When your
class needs to use a service, you can add a constructor parameter for that service. The
.NET Core runtime takes care of passing the service instance at run time. In this case, the
constructor injects an instance of the .NET Core configuration service by using the
IConfiguration parameter, which is used to retrieve the PowerBi:ServiceRootUrl

configuration value from appsettings.json. The ITokenAcquisition parameter, which is

named tokenAcquisition , holds a reference to the Microsoft authentication service
provided by the Microsoft.Identity.Web library. The ITokenAcquisition parameter is
used to acquire access tokens from Microsoft Entra ID.

The RequiredScopes field holds a string array that contains a set of delegated
permissions supported by the Power BI service API. When your application calls across
the network to acquire a Microsoft Entra token, it passes this set of delegated
permissions so that Microsoft Entra ID can include them in the access token it returns.

７ Note

Verify that your Microsoft Entra app is configured with the scopes required by your
web app. For more information, see Change your Microsoft Entra app's
permissions.

1. In your app's project, create a new folder titled Services.

2. In the Services folder, create a new file titled PowerBiServiceApi.cs.

3. Add the following code to PowerBiServiceApi.cs.

C#

using System;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.Extensions.Configuration;
using Microsoft.Identity.Web;
using Microsoft.Rest;
using Microsoft.PowerBI.Api;
using Microsoft.PowerBI.Api.Models;
using Newtonsoft.Json;

namespace AppOwnsData.Services {

// A view model class to pass the data needed to embed a single

report
public class EmbeddedReportViewModel {
public string Id;
public string Name;
public string EmbedUrl;
public string Token;
}

public class PowerBiServiceApi {

private ITokenAcquisition tokenAcquisition { get; }

private string urlPowerBiServiceApiRoot { get; }

public PowerBiServiceApi(IConfiguration configuration,

ITokenAcquisition tokenAcquisition) {
this.urlPowerBiServiceApiRoot =
configuration["PowerBi:ServiceRootUrl"];
this.tokenAcquisition = tokenAcquisition;
}

public const string powerbiApiDefaultScope =

"https://analysis.windows.net/powerbi/api/.default";

// A method to get the Azure AD token (also known as 'access

token')
public string GetAccessToken() {
return
this.tokenAcquisition.GetAccessTokenForAppAsync(powerbiApiDefaultScope)
.Result;
}

public PowerBIClient GetPowerBiClient() {

var tokenCredentials = new
TokenCredentials(GetAccessToken(), "Bearer");
return new PowerBIClient(new Uri(urlPowerBiServiceApiRoot),
tokenCredentials);
}
 public async Task<EmbeddedReportViewModel> GetReport(Guid
WorkspaceId, Guid ReportId) {

PowerBIClient pbiClient = GetPowerBiClient();

// Call the Power BI service API to get the embedding data.

var report = await
pbiClient.Reports.GetReportInGroupAsync(WorkspaceId, ReportId);

// Generate a read-only embed token for the report.

var datasetId = report.DatasetId;
var tokenRequest = new
GenerateTokenRequest(TokenAccessLevel.View, datasetId);
var embedTokenResponse = await
pbiClient.Reports.GenerateTokenAsync(WorkspaceId, ReportId,
tokenRequest);
var embedToken = embedTokenResponse.Token;

// Return the report embedded data to caller.

return new EmbeddedReportViewModel {
Id = report.Id.ToString(),
EmbedUrl = report.EmbedUrl,
Name = report.Name,
Token = embedToken
};
}

}
}

Modify the HomeController.cs file

In this code example, you use dependency injection to modify the HomeController.cs file.
By following a previous step, you configured the PowerBiServiceApi class as a service by
calling services.AddScoped in the ConfigureServices method. With this code, you add a
PowerBiServiceApi parameter to the constructor, and the .NET Core runtime creates a
PowerBiServiceApi instance and pass it to the constructor.

From the Controllers folder, open the HomeController.cs file and add the following code
to it:

C#

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using AppOwnsData.Models;
using AppOwnsData.Services;

namespace AppOwnsData.Controllers
{
[Authorize]
public class HomeController : Controller
{
private PowerBiServiceApi powerBiServiceApi;

public HomeController(PowerBiServiceApi powerBiServiceApi)

{
this.powerBiServiceApi = powerBiServiceApi;
}

[AllowAnonymous]
public IActionResult Index()
{
return View();
}

public async Task<IActionResult> Embed() {

// Replace these two GUIDs with the workspace ID and report ID

you recorded earlier.
Guid workspaceId = new Guid("11111111-1111-1111-1111-
111111111111");
Guid reportId = new Guid("22222222-2222-2222-2222-
222222222222");

var viewModel = await powerBiServiceApi.GetReport(workspaceId,

reportId);

return View(viewModel);
}

[AllowAnonymous]
[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None,
NoStore = true)]
public IActionResult Error()
{
return View(new ErrorViewModel { RequestId =
Activity.Current?.Id ?? HttpContext.TraceIdentifier });
}
}
}

Step 5 - Build your app's client side

For client-side implementation, you need to create or modify the files that are listed in
the following table:

ﾉ Expand table

File Use

embed.js Contains the client-side JavaScript code

Embed.cshtml Contains your app's document object model (DOM) and a DIV for embedding the
report

Create a container for your embedded report

In this tutorial, you create the Embed.cshtml file, which has a div element that's a
container for your embedded report, and three scripts.

1. In the View/Home folder, create a file called Embed.cshtml.

2. Add the following code to the Embed.cshtml file.

HTML

@model AppOwnsData.Services.EmbeddedReportViewModel;

<div id="embed-container" style="height:800px;"></div>

@section Scripts {

<!-- powerbi.min.js is the JavaScript file that loads the client-

side Power BI JavaScript API library.
Make sure that you're working with the latest library version.
You can check the latest library available in
https://cdnjs.com/libraries/powerbi-client -->
<script src="https://cdn.jsdelivr.net/npm/powerbi-
[email protected]/dist/powerbi.min.js"></script>

<!-- This script creates a JavaScript object named viewModel which

is accessible to the JavaScript code in embed.js. -->
<script>
var viewModel = {
reportId: "@Model.Id",
embedUrl: "@Model.EmbedUrl",
token: "@Model.Token"
};
</script>

<!-- This script specifies the location of the embed.js file -->
 <script src="~/js/embed.js"></script>
}

Add client-side JavaScript to embed your report

To embed Power BI content, you need to create a configuration object. To learn more
about creating the configuration object, see Embed a report.

In this tutorial, you create a JavaScript file named embed.js with a configuration object
for embedding your report that uses the variable models .

You can initialize models by using a call to window['powerbi-client'].models . The

models variable is used to set configuration values such as models.Permissions.All ,

models.TokenType.Aad , and models.ViewMode.View .

The powerbi.embed function uses the models configuration object to embed your report.

1. In the wwwroot/js folder, create a file called embed.js.

2. Add the following code to the embed.js file.

JavaScript

$(function () {

// 1 - Get DOM object for the div that's the report container.
var reportContainer = document.getElementById("embed-container");

// 2 - Get the report embedding data from the view model.

var reportId = window.viewModel.reportId;
var embedUrl = window.viewModel.embedUrl;
var token = window.viewModel.token

// 3 - Embed the report by using the Power BI JavaScript API.

var models = window['powerbi-client'].models;

var config = {
type: 'report',
id: reportId,
embedUrl: embedUrl,
accessToken: token,
permissions: models.Permissions.All,
tokenType: models.TokenType.Embed,
viewMode: models.ViewMode.View,
settings: {
panes: {
filters: { expanded: false, visible: true },
pageNavigation: { visible: false }
}
 }
};

// Embed the report and display it within the div container.

var report = powerbi.embed(reportContainer, config);

// 4 - Add logic to resize the embed container on a window resize

event.
var heightBuffer = 12;
var newHeight = $(window).height() - ($("header").height() +
heightBuffer);
$("#embed-container").height(newHeight);
$(window).resize(function () {
var newHeight = $(window).height() - ($("header").height() +
heightBuffer);
$("#embed-container").height(newHeight);
});

});

Step 6 - Run your application

After you've followed all previous steps, you're ready to run your application. Try
running your application, and experiment with the way your Power BI report is
embedded. You can use the Power BI embedded analytics Client APIs to enhance your
app by using client-side APIs.

） Important

If you used free embed trial tokens for development, you must buy a capacity for
production. Until a capacity is purchased, the Free trial version banner continues to
appear at the top of the embedded report.

When your app is ready, you can move your embedded app to production.

Related content
Embedded analytics application tokens

Move your embedded app to production

Capacity and SKUs in Power BI embedded analytics

 Capacity planning in Power BI embedded analytics

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Tutorial: Embed a Power BI report in an
application for your organization
Article • 06/03/2024

This tutorial explains how to embed a Power BI report in a .NET 5.0 application, as part
of the embed for your organization (also known as user owns data) solution. In an embed
for your organization solution, your app users need to authenticate against Power BI
with their own credentials.

In this tutorial, you learn how to embed:

＂ A Power BI report
＂ In an embed for your organization app
＂ Using .NET 5.0
＂ With the Microsoft.Identity.Web library (this library is also supported in .NET Core)

７ Note

The full solution used in this tutorial, is available from the DOTNET5-
UserOwnsData-Tutorial GitHub repository.

Prerequisites
A Power BI Pro or Premium Per User (PPU) license.

７ Note

The embed for your organization solution, is not supported on capacities

based on A SKUs. An A SKU can only be used for the embed for your
customers solution.

A Power BI workspace with a report.

Your own Microsoft Entra tenant.

An Microsoft Entra app.

A .NET Core 5 model view controller (MVC) app.

.NET Core 5 SDK (or higher).

 An integrated development environment (IDE). We recommend using one of the
following environments:
Visual Studio .
Visual Studio Code (with the C# extension ).

Resources
In this tutorial, you use:

Power BI REST Reports API - to embed the URL and retrieve the embed token.
Microsoft Identity Web authentication library.
Power BI embedded analytics Client APIs - to embed the report.

Method
To embed Power BI content in an embed for your organization solution, follow these
steps:

1. Configure your Microsoft Entra app

2. Get the embedding parameter values
3. Add the required NuGet packages
4. Enable server side authentication
5. Build your app's client side
6. Run your application

Step 1 - Configure your Microsoft Entra app

When your web app calls Power BI, it needs an Microsoft Entra token to call Power BI
REST APIs and embed Power BI items such as reports, dashboards, or tiles.

If you don't have a Microsoft Entra app, create one using the instructions in Register a
Microsoft Entra application to use with Power BI.

To configure your Microsoft Entra app, follow the instructions in Configure your
Microsoft Entra app.

Step 2 - Get the embedding parameter values

To embed your report, you need the following values:

Domain
 Tenant ID
Client ID
Client secret
Workspace ID
Report ID

Domain and tenant ID

If you don't know your domain or tenant ID, see Find the Microsoft Entra tenant ID and
primary domain name.

７ Note

To embed content for a user on a different tenant (a guest user), you need to
adjust the authorityUri parameter.

Client ID
To get the client ID GUID (also know as application ID), follow these steps:

1. Log into Microsoft Azure .

2. Search for App registrations and select the App registrations link.

3. Select the Microsoft Entra app you're using for embedding your Power BI content.

4. From the Overview section, copy the Application (client) ID GUID.

Client secret
To get the client secret, follow these steps:

1. Log into Microsoft Azure .

2. Search for App registrations and select the App registrations link.

3. Select the Microsoft Entra app you're using for embedding your Power BI content.

4. Under Manage, select Certificates & secrets.

5. Under Client secrets, select New client secret.

 6. In the Add a client secret pop-up window, provide a description for your
application secret, select when the application secret expires, and select Add.

7. From the Client secrets section, copy the string in the Value column of the newly
created application secret. The client secret value is your client ID.

７ Note

Make sure you copy the client secret value when it first appears. After navigating
away from this page, the client secret will be hidden and you'll not be able to
retrieve its value.

Workspace ID
To get the workspace ID GUID, follow these steps:

1. Sign in to Power BI service.

2. Open the report you want to embed.

3. Copy the GUID from the URL. The GUID is the number between /groups/ and
/reports/.

７ Note

To get the workspace ID programmatically, use the Get Groups API.

Report ID
To get the report ID GUID, follow these steps:

1. Sign in to Power BI service.

2. Open the report you want to embed.

3. Copy the GUID from the URL. The GUID is the number between /reports/ and
/ReportSection.
 ７ Note

To get the report ID programmatically, use the Get Reports In Group API.

Step 3 - Add the required NuGet packages

Before you start, you need to add the Microsoft.Identity.Web , and
Microsoft.PowerBI.Api NuGet packages to your app.

Add the following NuGet packages to your app:

In VS Code, open a terminal and type in the following code.

In Visual studio, navigate to Tools > NuGet Package Manager > Package Manager
Console and type in the following code.

PowerShell

dotnet add package Microsoft.Identity.Web -v 0.3.0-preview

dotnet add package Microsoft.Identity.Web.UI -v 0.3.0-preview
dotnet add package Microsoft.PowerBI.Api

If your app previously used Microsoft.AspNetCore to authenticate, remove this package

from your project by typing:

PowerShell

dotnet remove package Microsoft.AspNetCore.Authentication.AzureAD.UI

Step 4 - Enable server-side authentication

Enable server-side authentication in your app, by creating or modifying the files in the
following table.

ﾉ Expand table

File Use

Startup.cs Initialize the Microsoft.Identity.Web authentication service

appsettings.json Authentication details

 File Use

PowerBiServiceApi.cs Get the Microsoft Entra token and embedding metadata

HomeController.cs Pass embedding data as a model to the view

Configure your startup file to support

Microsoft.Identity.Web

Modify the code in Startup.cs to properly initialize the authentication service provided
by Microsoft.Identity.Web .

Add the following code snippet to your app's Startup.cs file.

７ Note

The code in ConfigureServices accomplishes several important things:

1. The call to AddMicrosoftWebAppCallsWebApi configures the Microsoft

Authentication Library to acquire access tokens (Microsoft Entra tokens).
2. The call to AddInMemoryTokenCaches configures a token cache that the
Microsoft Authentication Library will use to cache access tokens and refresh
tokens behind the scenes
3. The call to services.AddScoped(typeof(PowerBiServiceApi)) configures the
PowerBiServiceApi class as a service class that can be added to other classes

using dependency injection.

C#

using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.Identity.Web.UI;
using UserOwnsData.Services;

namespace UserOwnsData {

public class Startup {

public Startup (IConfiguration configuration) {

Configuration = configuration;
}

public IConfiguration Configuration { get; }

 // This method gets called by the runtime. Use this method to add
services to the container.
public void ConfigureServices (IServiceCollection services) {

services
.AddMicrosoftIdentityWebAppAuthentication(Configuration)

.EnableTokenAcquisitionToCallDownstreamApi(PowerBiServiceApi.RequiredScopes)
.AddInMemoryTokenCaches();

services.AddScoped (typeof (PowerBiServiceApi));

var mvcBuilder = services.AddControllersWithViews (options => {

var policy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
options.Filters.Add (new AuthorizeFilter (policy));
});

mvcBuilder.AddMicrosoftIdentityUI();

services.AddRazorPages();

}
}
}

Create an authentication details file

In this tutorial, the appsettings.json file contains sensitive information such as client ID
and client secret. For security reasons, we don't recommend keeping this information in
the settings file. When embedding in your application, consider a more secure method
such as Azure Key Vault for keeping this information.

1. In your project, create a new file and call it appsettings.json.

2. Add the following code to appsettings.json:

JSON

{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "",
"TenantId": "",
"ClientId": "",
"ClientSecret": "",
"CallbackPath": "/signin-oidc",
"SignedOutCallbackPath": "/signout-callback-oidc"
 },
"PowerBi": {
"ServiceRootUrl": "https://api.powerbi.com"
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}

3. Fill in the embedding parameter values obtained from Step 2 - Get the embedding
parameter values.

Domain - Domain and tenant ID

TenantId - Domain and tenant ID

ClientId - Client ID
ClientSecret - Client secret

７ Note

In the previous code snippet, the PowerBi:ServiceRootUrl parameter is added as a

custom configuration value to track the base URL to the Power BI service. When
programming against the Power BI service in the Microsoft public cloud, the URL is
https://api.powerbi.com/ . However, the root URL for the Power BI service will be

different in other clouds such as the government cloud. Therefore, this value is
stored as a project configuration value so it is easy to change when required.

Get the Microsoft Entra access token and call the Power
BI service
In order to embed Power BI content (such as reports and dashboards), your app needs
to get an Microsoft Entra token. To get the token, you need a configuration object.

The code in this section uses the .NET Core dependency injection pattern. When your
class needs to use a service, you can add a constructor parameter for that service and
the .NET Core runtime takes care of passing the service instance at run time. In this case,
the constructor is injecting an instance of the .NET Core configuration service using the
IConfiguration parameter, which is used to retrieve the PowerBi:ServiceRootUrl
configuration value from appsettings.json. The ITokenAcquisition parameter, which is
named tokenAcquisition holds a reference to the Microsoft authentication service
provided by the Microsoft.Identity.Web library and is used to acquire access tokens
from Microsoft Entra ID.

The RequiredScopes field holds a string array containing a set of delegated permissions
supported by the Power BI service API. When your application calls across the network
to acquire a Microsoft Entra token, passes this set of delegated permissions so that
Microsoft Entra ID can include them in the access token it returns.

７ Note

Verify that your Microsoft Entra app is configured with the scopes required by your
web app. For more information, see Change your Microsoft Entra app's
permissions.

1. In your app's project, create a new folder titled Services.

2. In the Services folder, create a new file titled PowerBiServiceApi.cs.

3. Add the following code to PowerBiServiceApi.cs.

C#

using Microsoft.Identity.Web;
using Microsoft.PowerBI.Api;
using Microsoft.PowerBI.Api.Models;
using Microsoft.Rest;
using Newtonsoft.Json;

namespace UserOwnsData.Services {

// A view model class to pass the data needed to embed a single

report.
public class EmbeddedReportViewModel {
public string Id;
public string Name;
public string EmbedUrl;
public string Token;
}

public class PowerBiServiceApi {

private ITokenAcquisition tokenAcquisition { get; }
private string urlPowerBiServiceApiRoot { get; }

public PowerBiServiceApi(IConfiguration configuration,

ITokenAcquisition tokenAcquisition) {
this.urlPowerBiServiceApiRoot =
configuration["PowerBi:ServiceRootUrl"];
 this.tokenAcquisition = tokenAcquisition;
}

public static readonly string[] RequiredScopes = new string[] {

"https://analysis.windows.net/powerbi/api/Report.Read.All"
};

// A method to get the Azure AD token (also known as 'access

token')
public string GetAccessToken() {
return
this.tokenAcquisition.GetAccessTokenForUserAsync(RequiredScopes).Result
;
}

public PowerBIClient GetPowerBiClient() {

var tokenCredentials = new TokenCredentials(GetAccessToken(),
"Bearer");
return new PowerBIClient(new Uri(urlPowerBiServiceApiRoot),
tokenCredentials);
}

public async Task<EmbeddedReportViewModel> GetReport(Guid

WorkspaceId, Guid ReportId) {
PowerBIClient pbiClient = GetPowerBiClient();
// Call the Power BI Service API to get embedding data
var report = await
pbiClient.Reports.GetReportInGroupAsync(WorkspaceId, ReportId);

// Return report embedding data to caller

return new EmbeddedReportViewModel {
Id = report.Id.ToString(),
EmbedUrl = report.EmbedUrl,
Name = report.Name,
Token = GetAccessToken()
};
}

Modify the HomeController.cs file

In this code example, you use dependency injection. As you registered the
PowerBiServiceApi class as a service by calling services.AddScoped in the

ConfigureServices method. You can add a PowerBiServiceApi parameter to the

constructor, and the .NET Core runtime takes care of creating a PowerBiServiceApi
instance and passing it to the constructor.
From the Controllers folder, open the HomeController.cs file and add it to the following
code snippet:

C#

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using UserOwnsData.Models;
using UserOwnsData.Services;

namespace UserOwnsData.Controllers {
[Authorize]
public class HomeController : Controller {

private PowerBiServiceApi powerBiServiceApi;

public HomeController (PowerBiServiceApi powerBiServiceApi) {

this.powerBiServiceApi = powerBiServiceApi;
}

[AllowAnonymous]
public IActionResult Index() {
return View();
}

public async Task<IActionResult> Embed() {

Guid workspaceId = new Guid("11111111-1111-1111-1111-
111111111111");
Guid reportId = new Guid("22222222-2222-2222-2222-
222222222222");
var viewModel = await powerBiServiceApi.GetReport(workspaceId,
reportId);
return View(viewModel);
}

[AllowAnonymous]
[ResponseCache (Duration = 0, Location = ResponseCacheLocation.None,
NoStore = true)]
public IActionResult Error() {
return View (new ErrorViewModel { RequestId =
Activity.Current?.Id ?? HttpContext.TraceIdentifier });
}
}
}

Step 5 - Build your app's client side

For client-side implementation, you need to create or modify the files in the following
table.
 ﾉ Expand table

File Use

embed.js Contains the client-side JavaScript code

Embed.cshtml Contains your app's document object model (DOM), and a DIV for embedding
the report

Create a container for your embedded report

Create the Embed.cshtml file, which has a div element used as a container for your
embedded report, and three scripts.

1. In the View > Home folder, create a file called Embed.cshtml.

2. Add the following code snippet to the Embed.cshtml file.

HTML

@model UserOwnsData.Services.EmbeddedReportViewModel;

<div id="embed-container" style="height:800px;"></div>

@section Scripts {

<!-- powerbi.min.js is the JavaScript file that loads the client-

side Power BI JavaScript API library.
Make sure that you're working with the latest library version.
You can check the latest library available in
https://cdnjs.com/libraries/powerbi-client -->
<script src="https://cdn.jsdelivr.net/npm/powerbi-
[email protected]/dist/powerbi.min.js"></script>

<!-- This script creates a JavaScript object named viewModel which

is accessible to the JavaScript code in embed.js. -->
<script>
var viewModel = {
reportId: "@Model.Id",
embedUrl: "@Model.EmbedUrl",
token: "@Model.Token"
};
</script>

<!-- This script specifies the location of the embed.js file -->
<script src="~/js/embed.js"></script>
}

Add client-side JavaScript to embed your report

To embed Power BI content, you need to create a configuration object. To learn more
about creating the configuration object, see Embed a report.

In this section, you create a JavaScript file named embed.js with a configuration object
for embedding your report, using the variable models .

models is initialized using a call to window['powerbi-client'].models . The models

variable is used to set configuration values such as models.Permissions.All ,

models.TokenType.Aad , and models.ViewMode.View .

The powerbi.embed function uses the models configuration object to embed your report.

1. In the wwwroot > js folder, create a file called embed.js.

2. Add the following code snippet to the embed.js file.

JavaScript

$(function(){
// 1 - Get DOM object for div that is report container
let reportContainer = document.getElementById("embed-container");

// 2 - Get report embedding data from view model

let reportId = window.viewModel.reportId;
let embedUrl = window.viewModel.embedUrl;
let token = window.viewModel.token

// 3 - Embed report using the Power BI JavaScript API.

let models = window['powerbi-client'].models;
let config = {
type: 'report',
id: reportId,
embedUrl: embedUrl,
accessToken: token,
permissions: models.Permissions.All,
tokenType: models.TokenType.Aad,
viewMode: models.ViewMode.View,
settings: {
panes: {
filters: { expanded: false, visible: true },
pageNavigation: { visible: false }
}
}
};

// Embed the report and display it within the div container.

let report = powerbi.embed(reportContainer, config);

// 4 - Add logic to resize embed container on window resize event

let heightBuffer = 12;
let newHeight = $(window).height() - ($("header").height() +
 heightBuffer);
$("#embed-container").height(newHeight);
$(window).resize(function() {
var newHeight = $(window).height() - ($("header").height() +
heightBuffer);
$("#embed-container").height(newHeight);
});

});

Step 6 - Run your application

After you've made all the adjustments listed in this tutorial, you're ready to run your
application. Execute your application and experiment with the way your Power BI report
is embedded. You can use the Power BI embedded analytics Client APIs to enhance your
app using client side APIs.

When your app is ready, you can move your embedded app to production.

Related content
Embedded analytics application tokens

Move your embedded app to production

Capacity and SKUs in Power BI embedded analytics

Capacity planning in Power BI embedded analytics

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Embed Power BI paginated reports
Article • 01/08/2024

With Power BI embedded analytics, you can create Power BI content that displays
paginated reports in a fully integrated and interactive application. Embed paginated
reports using the solution that works best for you, embed for your customers or embed
for your organization.

This article describes how to embed paginated reports using the embedding sample
tutorials.

Prerequisites
To get started, you need:

Embed for your customers

A service principal

Your own Microsoft Entra tenant setup

A capacity

If you don't have an Azure subscription, create a free account before you begin.

Method
To embed a paginated report using the sample app, follow these steps:

1. Create a workspace.

2. Create a capacity.

3. Assign a workspace to a capacity.

4. Create and upload your paginated report.

5. Embed content using the sample application.

Step 1 - Create a workspace

Embed for your customers

As you're using a service principal to sign into your application, you need to create
a workspace.

Your service principal must also be an admin or member of the Power BI

workspaces.

Step 2 - Create a capacity

Embed for your customers

Before you import or upload a paginated report to embed, you must assign the
workspace containing the report to a capacity. There are two types of capacity you
can choose from:

Power BI Premium - To embed a paginated report, you need an EM or P SKU.

For more information about this subscription, see What is Power BI Premium?.
Azure Power BI Embedded - You can purchase a capacity from the Microsoft
Azure portal . This subscription uses the A SKUs. For details on how to create
a Power BI Embedded capacity, see Create Power BI Embedded capacity in the
Azure portal.

The following table describes the resources and limits of each SKU. To determine
which capacity best fits your needs, see the which SKU should I purchase for my
scenario table.

ﾉ Expand table

Capacity Nodes V-cores RAM (GB)

EM1/A1 1 2.5

EM2/A2 2 5

EM3/A3 4 10

P1/A4 8 25

P2/A5 16 50

P3/A6 32 100
Step 3 - Assign a workspace to a capacity
Embed for your customers

Once you create a capacity, assign your app workspace to that capacity.

To assign a capacity to a workspace using a service principal, work with the Power BI
REST API. When you're using the Power BI REST APIs, make sure to work with the
service principal object ID.

７ Note

You can also import paginated reports into a workspace using the Power BI
REST APIs.

Step 4 - Create and upload your paginated

report
You can create your paginated report using Power BI Report Builder, and then upload
the report to the service.

７ Note

The person who uploads the paginated report needs a Power BI Pro or Premium
Per User (PPU) license to publish to a workspace.

Step 5 - Embed content using the sample

application
Embed for your customers

Follow the steps in the embed content for your customers tutorial. Skip Step 4 -
Create and publish a Power BI report and work with the paginated report you
uploaded, instead of the sample report suggested in the tutorial.

To use a Power BI semantic model as a data source:

 Make sure the tenant setting Allow XMLA endpoints and Analyze in Excel
with on-premises datasets is enabled.
In the Power BI portal, set the XMLA endpoint to Read Only or Read Write
as described in enable read-write for a Premium capacity. You only need to
set up the endpoint once per capacity.
Generate a multi-resource embed token with the dataset ID specified in the
request, and the XmlaPermissions set to Read Only.

To use a single sign-on (SSO) enabled data source:

Power BI supports SSO-enabled data sources if the data sources directly
connect to the paginated report or connect to a Power BI semantic model
that's the data source of the paginated report.
When you embed a paginated report with SSO-enabled data sources, you
must provide the identity blob for the data source in the
DatasourceIdentity at the time you generate a multi-resource embed token.

For more information on embedding tokens, see Embedded analytics access tokens.

Considerations and limitations

Embed for your customers limitations

For a full list of supported datasets and their authentication methods, see
Supported data sources for Power BI paginated reports.
You must use a service principal. You can't have a master user.
You can't work with a Premium Per User (PPU).
When you embed a paginated report with a Power BI semantic model, two
conditions apply:
The paginated report and the Power BI semantic model must reside in a
Premium per capacity or Embedded workspace (they can reside in two
different workspaces).
The person who generates the embed token must have Write permissions
in the workspaces of both the report and the semantic model.
You can't currently embed a paginated report connected to Azure Analysis
Services with single sign-on (SSO) enabled.

Paginated reports don't support client-side events (like loaded or rendered ).

 Embedding paginated reports with a real-time dataset (push dataset) is not
supported.

Related content
Tutorial: Embed a Power BI report in an application for your organization
Capacity and SKUs in Power BI embedded analytics
Considerations when generating an embed token
Embed Power BI content in Salesforce
Article • 06/03/2024

Salesforce is a world-renowned customer relationship management (CRM) solution.

Power BI embedded analytics lets you embed Power BI content, such as reports and
dashboards, in Salesforce.

This article links to two samples that show how to develop by using Power BI embedded
analytics in a Salesforce environment. The two developer samples demonstrate two
different solutions that enable embedding Power BI content in Salesforce: the embed for
your customers solution and the embed for your organization solution.

Prerequisites
You must be familiar with both Power BI and Salesforce. It's helpful to have experience
developing with Power BI embedded analytics and be familiar with the Salesforce
environment, preferably with the Salesforce Developer Experience (SFDX).

Embed for your customers solution

In the embed for your customers solution, you create an embedded application by using
your own Power BI account. The embed for your customers solution is also known as an
app owns data solution. Your customers don't need to use Power BI credentials to view
and interact with the embedded content.

Apex class
The Salesforce embed for your customers solution uses a service principal and is built on
top of an Apex class named PowerBiEmbedManager .

Here are some advantages of the PowerBiEmbedManager Apex class:

The PowerBiEmbedManager Apex class is programmed to interact with both

Microsoft Entra ID and the Power BI REST APIs.

The PowerBiEmbedManager Apex class implements Client Credentials Flow when it

interacts with Microsoft Entra ID to acquire an app-only access token. App-only
access tokens are important because they allow you to call the Power BI REST APIs
under the identity of a service principal, instead of calling under the identity of a
user.
Lightning Aura
The Salesforce embed for your customers solution contains a Lightning Aura
component named powerBiReportAura . When you add an instance of the
powerBiReportAura component to a Lightning application page, you must configure it

with a specific Power BI Workspace ID and Report ID. This design makes it possible to
add multiple instances of the powerBiReportAura component, and configure each
instance to embed a different Power BI report.

Embed for your customers solution Salesforce developer

sample
To embed Power BI content by using the embed for your customers Salesforce solution,
follow the instructions in the SalesforceAppOwnsDataEmbedding GitHub repository.

Embed for your organization solution

In the embed for your organization solution, you create an embedded application that
requires your customers to sign in with their own Power BI credentials. The embed for
your organization solution is also known as a user owns data solution. Signed in
customers can view and interact with the embedded content according to their Power BI
permissions.

Single page application

The Salesforce embed for your organization Salesforce solution uses a simple single
page application (SPA) that implements Power BI reports. The solution is built by using
three essential files:

index.html
app.css
app.js

Client-side libraries
In the Salesforce embed for your organization Salesforce solution, powerbi.js is used to
access the Power BI embedded analytics Client APIs.
Embed for your organization solution Salesforce
developer sample
To embed Power BI content that uses the embed for your organization solution, follow
the instructions in the SalesforceUserOwnsDataEmbedding GitHub repository.

Related content
Embed Power BI content into an application for your customers

Embed Power BI content into an application for your organization

Power BI embedded analytics Client APIs

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Q&A in Power BI embedded analytics
Article • 02/04/2024

Power BI embedded analytics offers you a way to incorporate Q&A into an application.
Your users can ask questions using natural language, and receive immediate answers in
the form of visuals like charts or graphs.

There are two modes for embedding Q&A within your application: interactive and result
only. Interactive mode allows you to type in questions and have them displayed within
the visual. If you have a saved question, or a set question you want to display, you can
use the result only mode by populating the question in your embed config.

Here's an example of the JavaScript code:

JavaScript

// Embed configuration used to describe the what and how to embed.

// This object is used when calling powerbi.embed within the JavaScript API.
// You can find more information at https://github.com/Microsoft/PowerBI-
JavaScript/wiki/Embed-Configuration-Details.
var config= {
type: 'qna',
tokenType: models.TokenType.Embed | models.TokenType.Aad,
accessToken: access token value,
embedUrl: https://app.powerbi.com/qnaEmbed (groupId to be appended as
query parameter if required),
datasetIds: array of requested data set ids (at the moment we support
 only one dataset),
viewMode: models.QnaMode.Interactive | models.QnaMode.ResultOnly,
question: optional parameter for Explore mode (QnaMode.Interactive)
and mandatory for Render Result mode (QnaMode.ResultOnly)
};

// Get a reference to the embedded QNA HTML element

var qnaContainer = $('#qnaContainer')[0];

// Embed the QNA and display it within the div container.

var qna = powerbi.embed(qnaContainer, config);

Set question
If you use result mode with a set question, you can inject more questions into the
frame. The answer to the new question will immediately replace the previous result. A
new visual is rendered matching the new question.

One example of this usage would be a frequently asked question list. The user could go
through the questions and have them answered within the same embedded part.

Code snippet for JS SDK usage:

JavaScript

// Get a reference to the embedded Q&A HTML element

var qnaContainer = $('#qnaContainer')[0];

// Get a reference to the embedded Q&A.

qna = powerbi.get(qnaContainer);

qna.setQuestion("This year sales")

.then(function (result) {
…….
})
.catch(function (errors) {
…….
});

Visual rendered event

For interactive mode, the application can be notified with a data changed event each
time the rendered visual changes to target the updated input query as it is being typed.

Listening to the visualRendered event allows you to save questions for use later.

Code snippet for JS SDK usage:

 JavaScript

// Get a reference to the embedded Q&A HTML element

var qnaContainer = $('#qnaContainer')[0];

// Get a reference to the embedded Q&A.

qna = powerbi.get(qnaContainer);

// qna.off removes a given event listener if it exists.

qna.off("visualRendered");

// qna.on will add an event listener.

qna.on("visualRendered", function(event) {
…….
});

Embed token
Create an embed token from a semantic model to start a Q&A part. For more
information, see the generate token operation.

Related content
Try out Q&A embedding with the JavaScript embed sample

More questions? Ask the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Embed a report in a secure portal or
website
Article • 05/13/2024

With the Embed option for Power BI reports, you can easily and securely embed reports
in internal web portals. These portals can be cloud-based or hosted on-premises, such
as SharePoint 2019. Embedded reports respect all item permissions and data security
through row-level security (RLS) and Analysis Services tabular model object-level
security (OLS). They provide no-code embedding into any portal that accepts a URL or
iframe.

The Embed option supports URL filters and URL settings. It allows you to integrate with
portals by using a low-code approach that requires only basic HTML and JavaScript
knowledge.

） Important

Due to ongoing Chromium security updates, the Embed option no longer works
exactly as it used to, and users may be asked to authenticate more than once. To
address this, consider creating your own Power BI embedded solution.

How to embed Power BI reports into portals

1. Open a report in the Power BI service.

2. On the File menu, select Embed report > Website or portal.

3. In the Secure embed code dialog, select the value under Here's a link you can use
to embed this content. Or if you'd like to use an iframe in a blog or website, select
the value under HTML you can paste into a website.

4. Whether a user opens a report URL directly, or one that's embedded in a web
portal, report access requires authentication. The following screen appears if a user
hasn't signed in to Power BI in their browser session. When they select Sign-In, a
new browser window or tab should open. Have them check for pop-up blockers if
they don't get prompted to sign in.
 5. After the user has signed in, the report opens, showing the data and allowing page
navigation and filter setting. Only users with view permission can see the report in
Power BI. All row-level security (RLS) rules are also applied. The users need to be
correctly licensed. They need a Power BI Pro or Premium Per User (PPU) license, or
the content needs to be in a workspace that's in a Power BI Premium capacity.
Users need to sign in each time they open a new browser window. However, after
they're signed in, other reports load automatically.

6. When you use an iframe, you might need to edit the height, and width values to
have it fit in your portal's web page.

Grant report access

The Embed option doesn't automatically permit users to view the report. View
permissions are set in the Power BI service.
In the Power BI service, you can share embedded reports with users who require access.
If you use a Microsoft 365 Group, you can list the user as a workspace member.

Licensing
To view the embedded report, you need either a Power BI Pro or Premium Per User
(PPU) license. Or, the content needs to be in a workspace that's in a Power BI Premium
capacity (EM or P SKU).

Customize your embed experience by using

URL settings
You can customize the user experience by using the embed URL's input settings. In the
provided iframe, you can update the URL's src settings.

ﾉ Expand table

Property Description

pageName You can use the pageName query string parameter to set which report page to
open. You can find this value at the report URL's end when you view a report in the
Power BI service, as shown later in this article.

URL Filters You can use URL Filters in the embed URL that you received from the Power BI UI to
filter the embed content. This way you can build low-code integrations with only
basic HTML and JavaScript experience.

Set which page opens for an embedded report

You can find the pageName value at the end of report's URL when you view a report in
the Power BI service.

1. Open the report from the Power BI service in your web browser, and then copy the
address bar URL.

2. Append the pageName property and its value to the end of the URL.
Filter report content by using URL filters
You can use URL Filters to provide different report views. For example, the following URL
filters the report to show data for the energy industry.

Using the combination of pageName and URL Filters can be powerful. You can build
experiences using basic HTML and JavaScript.

For example, here's a button you can add to an HTML page:

HTML

<button class="textLarge" onclick='show("ReportSection", "Energy");'

style="display: inline-block;">Show Energy</button>

When selected, the button calls a function to update the iframe with an updated URL,
which includes the Energy industry filter.

JavaScript

function show(pageName, filterValue)

var newUrl = baseUrl + "&pageName=" + pageName;

if(null != filterValue && "" != filterValue)

newUrl += "&$filter=Industries/Industry eq '" + filterValue + "'";

//Assumes there's an iFrame on the page with id="iFrame"

var report = document.getElementById("iFrame")

report.src = newUrl;

You can add as many buttons as you'd like to create a low-code custom experience.
Considerations and limitations
Paginated reports are supported with secure embed scenarios, and paginated
reports with URL parameters are also supported. For more information, see Pass a
report parameter in a URL for a paginated report in Power BI.

The secure embed option works for reports that are published to the Power BI
service.

To host securely embedded content, users must use HTTPS for their top-level
page. Using an unsecured host page to access securely embedded content isn't
supported.

The user needs to sign in to view the report whenever they open a new browser
window or tab.

For authentication, users need to have popup windows enabled.

If users have successfully accessed reports in the past but are now encountering
issues, they should clear their browser cache.

Some browsers require you to refresh the page after sign-in, especially when you
use InPrivate or Incognito modes.

You might encounter issues if you use unsupported browser versions. For a list of
browsers that Power BI supports, see Supported browsers for Power BI.

If your website sets the Cross-Origin-Opener-Policy (COOP) header to “same-

origin,” you can't log in to view your embedded content because MSAL doesn't
support this header. Instead, choose either "restrict-properties" (for Chromium-
based browsers) or "same-origin-allow-popups." Alternatively, if you can't change
the Cross-Origin-Opener-Policy, link to the embedded URL directly instead of
embedding it in an iframe.

The classic SharePoint Server isn't supported, because it requires Internet Explorer
versions earlier than 11, or enabling the compatibility view mode.

To achieve a single sign-on experience, use the Embed in SharePoint Online option,
or build a custom integration by using the user-owns-data embedding method.

The automatic authentication capabilities provided with the Embed option don't
work with the Power BI JavaScript API. They are blocked in PBI embedded client
SDK starting with the version 2.10.4. For the Power BI JavaScript API, use the user-
owns-data embedding method.
 The automatic authentication capabilities don't work when they're embedded in
applications, including in mobile and desktop applications.

The authentication token lifetime is controlled based on your Microsoft Entra

settings. When the authentication token expires, the user will need to sign in again
to get an updated authentication token. The default lifetime is one hour, but it
might be shorter or longer in your organization. You can't automatically refresh the
token in this scenario.

Related content
Ways to share your work in Power BI
Filter a report using query string parameters in the URL
Embed with report web part in SharePoint Online
Publish to web from Power BI

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Embedded analytics access tokens
Article • 02/05/2024

APPLIES TO: App owns data User owns data

Consuming Power BI content (such as reports, dashboards and tiles) requires an access
token. Depending on your solution, this token can be either an Microsoft Entra token, an
embed token, or both.

In the embed for your customers solution, the application generates an embed token
that grants your web users access to Power BI content.

７ Note

When you use the embed for your customers solution, you can use any
authentication method to allow access to your web app.

In the embed for your organization solution, your web app users authenticate against
Microsoft Entra ID by using their own credentials. Your customers have access to the
Power BI content that they have permission to access on the Power BI service.

Microsoft Entra token

For both embed for your customers and embed for your organization solutions, you need
an Microsoft Entra token. The Microsoft Entra token is required for all REST API
operations, and it expires after an hour.

In the embed for your customers solution, the Microsoft Entra token is used to
generate the embed token.

In the embed for your organization solution, the Microsoft Entra token is used to
access Power BI.

You can acquire a Microsoft Entra token in one of the following ways:

Use the external Postman tool to acquire a token. For more information, see this
Power BI Community thread . The request URL for a service principal must be
https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token , but for a

master user, it can be either

https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token or

https://login.microsoftonline.com/common/oauth2/token .
 Follow the sample solutions at PowerBI-Developer-Samples . For example:

For Embed for your customers see this AadService.cs file . Find the
authorityUrl and scopeBase at AppOwnsData/Web.config .

For Embed for your organization see this OwinOpenIdConnect.cs file . Find
authorityUrl at UserOwnsData/Web.config .

７ Note

You can find the authorityUrl and scopeBase values for some sovereign
clouds in Embed content in your app for government and national/regional
clouds.

Embed token
When you use the embed for your customers solution, your web app needs to know
which Power BI content a user can access. Use the embed token REST APIs to generate
an embed token, which specifies the following information:

The content your web app user can access

The web app user's access level (view, create, or edit)

For more information, see Considerations when generating an embed token.

Authentication flows
This section describes the different authentication flows for the embed for your
customers and embed for your organization solutions.

Embed for your customers

The embed for your customers solution uses a non-interactive authentication flow. In
an embed for your customers solution, users don't sign in to Microsoft Entra ID to
access Power BI. Instead, your web app uses a reserved Microsoft Entra identity to
authenticate against Microsoft Entra ID and generate the embed token. The
reserved identity can be either a service principal or a master user:

Service principal Your web app uses the Microsoft Entra service principal
object to authenticate against Microsoft Entra ID and get an app-only
 Microsoft Entra token. This app-only authentication method is recommended
by Microsoft Entra ID.

When using a service principal, you need to enable Power BI APIs access in the
Power BI service admin settings. Enabling access allows your web app to
access the Power BI REST APIs. To use API operations on a workspace, the
service principal needs to be a member or an admin of the workspace.

Master user Your web app uses a user account to authenticate against
Microsoft Entra ID and get the Microsoft Entra token. The master user account
needs to have a Power BI Pro or a Premium Per User (PPU) license.

When you use a master user account, you need to define your app's
delegated permissions (also known as scopes). The master user or tenant
admin has to give consent to use these permissions when using the Power BI
REST APIs.

After successful authentication against Microsoft Entra ID, your web app generates
an embed token to allow its users to access specific Power BI content.

７ Note

To embed by using the embed for your customers solution, you need a
capacity with an A, EM, or P SKU.
To move to production, you need a capacity.

The following diagram shows the authentication flow for the embed for your
customers solution.
 1. The web app user authenticates against your web app with your
authentication method.

2. Your web app uses a service principal or a master user to authenticate against
Microsoft Entra ID.

3. Your web app gets an Microsoft Entra token from Microsoft Entra ID and uses it
to access Power BI REST APIs. The authentication method you choose gives
access to the Power BI REST APIS, which depends on if the authentication
method is either a service principal or a master user.

4. Your web app calls an Embed Token REST API operation and requests the
embed token. The embed token specifies which Power BI content can be
embedded.

5. The REST API returns the embed token to your web app.

6. The web app passes the embed token to the user's web browser.

7. The web app user uses the embed token to access Power BI.

Related content
Considerations when generating an embed token
 Capacity and SKUs in Power BI embedded analytics

More questions? Try asking the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Generate an embed token
Article • 06/03/2024

APPLIES TO: App owns data User owns data

Generate token is a REST API that lets you generate a token for embedding a Power BI
report or semantic model in a web app or a portal. It can generate a token for a single
item or for multiple reports or semantic models. The token is used to authorize your
request against the Power BI service.

The generate token API uses a single identity (a master user or service principal) to
generate a token for an individual user, depending on that user's credentials in the app
(effective identity).

After successful authentication, access to the relevant data is granted.

７ Note

Generate token is the newer, version 2 API that works for both reports and
semantic models, and single or multiple items. It's preferred over the legacy version
1 APIs. For dashboards and tiles use the V1 Dashboards GenerateTokenInGroup
and Tiles GenerateTokenInGroup.

Securing your data

If you're handling data from multiple customers, there are two main approaches to
securing your data: Workspace-based isolation and Row-level security-based isolation.
You can find a detailed comparison between them in service principal profiles and row
level security.

We recommend using workspace-based isolation with profiles, but if you want to use
the RLS approach, review the RLS section at the end of this article.

Token permissions and security

In the generate token APIs, the GenerateTokenRequest section describes the token
permissions.

Access Level
 Use the allowEdit parameter to grant the user viewing or editing permissions.

Add the workspace ID to the embed token to allow the user to create new reports
(either SaveAs or CreateNew) in that workspace.

Row Level Security

With Row Level Security (RLS), the identity you use can be different from the identity of
the service principal or master user you're using to generating the token. By using
different identities, you can display embedded information according to the user you're
targeting. For example, in your application you can ask users to sign in, and then display
a report that only contains sales information if the signed in user is a sales employee.

If you're using RLS, you can sometimes leave out the user's identity (the EffectiveIdentity
parameter). When you don't use the EffectiveIdentity parameter, the token has access to
the entire database. This method can be used to grant access to users such as admins
and managers, who have permission to view the entire semantic model. However, you
can't use this method in every scenario. The table below lists the different RLS types, and
shows which authentication method can be used without specifying a user's identity.

The table also shows the considerations and limitation applicable to each RLS type.

ﾉ Expand table

RLS type Can I generate an Considerations and limitations

embed token without
specifying the
effective user ID?

Cloud Row Level ✔ Master user

Security (Cloud ✖ Service principal
RLS)

RDL (paginated ✖ Master user You can't use a master user to generate an embed
reports) ✔ Service principal token for RDL.

Analysis Services ✔ Master user The user generating the embed token also needs
(AS) on premises ✖ Service principal one of the following permissions:
live connection Gateway admin permissions
Datasource impersonate permission
(ReadOverrideEffectiveIdentity)

Analysis Services ✔ Master user The identity of the user generating the embed
(AS) Azure live ✖ Service principal token can't be overridden. Custom data can be
connection used to implement dynamic RLS or secure filtering.
 RLS type Can I generate an Considerations and limitations
embed token without
specifying the
effective user ID?

Note: Service principal must provide its object ID

as the effective identity (RLS username).

Single Sign On ✔ Master user An explicit (SSO) identity can be provided using the
(SSO) ✖ Service principal identity blob property in an effective identity
object

SSO and cloud ✔ Master user You must provide the following:
RLS ✖ Service principal Explicit (SSO) identity in the identity blob
property in an effective identity object
Effective (RLS) identity (username)

７ Note

Service principals must always provide the following information:

An identity for any item with an RLS semantic model.

For an SSO semantic model, an effective RLS identity with the contextual
(SSO) identity defined.

DirectQuery for Power BI semantic models

To embed Power BI report that has a semantic model with a Direct Query connection to
another Power BI semantic model, do the following:

In the Power BI portal, set the XMLA endpoint to Read Only or Read Write as
described in enable read-write for a Premium capacity. You only need to do this
once per capacity.
Generate a multi-resource embed token
Specify all dataset IDs in the request.
Set the XmlaPermissions to Read Only for each semantic model in the request.
For each Single Sign-on (SSO) enabled data source, provide the identity blob for
the data source in the DatasourceIdentity.

Renew tokens before they expire

Tokens come with a time limit. This means that after embedding a Power BI item, you
have a limited amount of time to interact with it. To give your users a continuous
experience, renew (or refresh) the token before it expires.

Dashboards and tiles

The Generate token works for reports and semantic models. To generate an embed
token for a dashboard or tile, use the version 1 Dashboards GenerateTokenInGroup or
Tiles GenerateTokenInGroup APIs. These APIs generate tokens for only one item at a
time. You can't generate a token for multiple items.

For these APIs:

Use the accessLevel parameter to determine the user's access level.

View - Grant the user viewing permissions.

Edit - Grant the user viewing and editing permissions (only applies when
generating an embed token for a report).

Create - Grant the user permissions to create a new report (only applies when
generating an embed token for creating a report). For report creation, you must
also supply the datasetId parameter.

Use the allowSaveAs boolean to let users save the report as a new report. This
setting is set to false by default, and only applies when generating an embed token
for a report.

Considerations and limitations

For security reasons, the lifetime of the embed token is set to the remaining
lifetime of the Microsoft Entra token used to call the GenerateToken API. Therefore,
if you use the same Microsoft Entra token to generate several embed tokens, the
lifetime of the generated embed tokens will be shorter with each call.

If the semantic model and item to be embedded are in two different workspaces,
the service principal or master user must be at least a member of both workspaces.

You can't create an embed token for My workspace.

Related content
Register an app
Power BI Embedded for your customers
 Embed Power BI content with service principal

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Connect a report to a semantic model
using dynamic binding
Article • 06/03/2024

APPLIES TO: App owns data User owns data

When a report is connected to a semantic model, you can use dynamic binding. The
connection between the report and the semantic model, is known as binding. When the
binding is determined at the point of embedding, as opposed to being predetermined
earlier, the binding is known as dynamic binding.

When embedding a Power BI report using dynamic binding, you can connect the same
report to different semantic models depending on the user's credentials.

This means that you can use one report to display different information, depending on
the semantic model it's connected to. For example, a report showing retail sale values
can be connected to different retailer semantic models, and produce different results,
depending on the semantic model of the retailer it's connected to.

The report and the semantic model don't need to reside in the same workspace. Both
workspaces (the one containing the report, and the one containing the semantic model)
must be assigned to a capacity.

As part of the embedding process, make sure you generate a token with sufficient
permissions, and adjust the config object.

Generating a token with sufficient permissions

Dynamic binding is supported for both Embedding for your organization and Embedding
for your customers scenarios. The table below describes the considerations for each
scenario.

ﾉ Expand table

Scenario Data Token Requirements

ownership

Embedding for User owns Access The user whose Microsoft Entra token is used,
your data token for must have appropriate permissions for all items
organization Power BI (reports, semantic models, etc.).
users
 Scenario Data Token Requirements
ownership

Embedding for App owns Access Must include permissions for both the report and
your customers data token for the dynamically bound semantic model. Use the
non-Power API for generating an embed token for multiple
BI users items, to generate an embed token that supports
multiple items.

７ Note

The maximum number of data sources allowed per user is 1000. This limit implies
that the combined number of datas sources used in the dynamic binding between
reports and semantic modelts by this user cannot exceed 1000.

Adjusting the config object

For dynamic binding to work, you need to add datasetBinding to the config object. To
learn how this is done, see Bind datasets dynamically to a report.

Related content
If you're new to embedding in Power BI, review these tutorials to learn how to embed
your Power BI content.

Embed Power BI content into an application for your customers

Embed Power BI content into an application for your organization

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Export Power BI report to file
Article • 07/04/2024

The exportToFile API enables exporting a Power BI report by using a REST call. The
following file formats are supported:

.pptx (PowerPoint)
.pdf
.png
When you export to a .png, a report with multiple pages is compressed into a
.zip file
Each file in the .zip represents a report page
The page names are the same as the return values of the Get Pages or Get
Pages in Group APIs

７ Note

Exporting a Power BI report to a file using the exportToFile API is not supported for
Premium Per User (PPU).

Usage examples
You can use the export feature in several ways. Here are a couple of examples:

Send to print button - In your application, create a button that when clicked on
triggers an export job. The job can export the viewed report as a .pdf or a .pptx.
When it's complete, the user can receive the file as a download. Using bookmarks
you can export the report in a specific state, including configured filters, slicers,
and other settings. As the API is asynchronous, it may take some time for the file to
be available.

Email attachment - Send an automated email at set intervals, with an attached .pdf
report. This scenario can be useful if you want to automate sending a weekly
report to executives. For more information, see Export and email a Power BI report
with Power Automate

Using the API

License requirements
 The report you're exporting must reside in a workspace backed by a Premium,
Embedded, or Fabric capacity.
The exportToFile API, is not supported for Premium Per User (PPU).

Admin settings
Before using the API, verify that the following admin tenant settings are enabled:

Export reports as PowerPoint presentations or PDF documents - Enabled by

default.
Export reports as image files - Required only for .png and disabled by default.

"Rendering" events
To make sure the export doesn't begin before the visual finishes rendering use the
"Rendering" events API and only begin the export when rendering is finished.

Polling
The API is asynchronous. When the exportToFile API is called, it triggers an export job.
After triggering an export job, use polling to track the job, until it's complete.

During polling, the API returns a number that represents the amount of work
completed. The work in each export job is calculated based on the total of exports in the
job. An export includes exporting a single visual, or a page with or without bookmarks.
All exports have the same weight. If for example, your export job includes exporting a
report with 10 pages, and the polling returns 70, it means the API processed seven out
of the 10 pages in the export job.

When the export is complete, the polling API call returns a Power BI URL for getting the
file. The URL is available for 24 hours.

Supported features
This section describes how to use the following supported features:

Selecting which pages to print

Exporting a page or a single visual
Bookmarks
Filters
Authentication
 Row Level Security (RLS)
Data protection
Localization
Dynamic binding

Selecting which pages to print

Specify the pages you want to print according to the Get Pages or Get Pages in Group
return value. You can also specify the order of the pages you're exporting.

Exporting a page or a single visual

You can specify a page or single visual to export. Pages can be exported with or without
bookmarks.

Depending on the type of export, you need to pass different attributes to the
ExportReportPage object. The following table specifies which attributes are required for
each export job.

７ Note

Exporting a single visual has the same weight as exporting a page (with or without
bookmarks). This means that in terms of system calculations, both operations carry
the same value.

ﾉ Expand table

Attribute Page Single Comments

visual

bookmark Optional Use to export a page in a specific state

pageName Use the GetPages REST API or the getPages client API.

visualName There are two ways to get the name of the visual:
Use the getVisuals client API.
Listen and log the visualClicked event, which is triggered
when a visual is selected. For more information, see How to
handle events
.

Bookmarks
Bookmarks can be used to save a report in a specific configuration, including applied
filters and the state of the report's visuals. You can use the exportToFile API to
programmatically export a report's bookmark, in two ways:

Export an existing bookmark

To export an existing report bookmark, use the name property, a unique (case
sensitive) identifier, which you can get using the bookmarks JavaScript API .

Export the report's state

To export the current state of the report, use the state property. For example, you
can use the bookmark's bookmarksManager.capture method to capture the changes
a specific user made to a report, and then export it in its current state using
capturedBookmark.state .

７ Note

Personal bookmarks and persistent filters are not supported.

Filters
Using reportLevelFilters in PowerBIReportExportConfiguration, you can export a
report in a filtered condition.

To export a filtered report, insert the URL query string parameters you want to use as
your filter, to ExportFilter. When you enter the string, you must remove the ?filter=
part of the URL query parameter.

The table includes a few syntax examples of strings you can pass to ExportFilter .

ﾉ Expand table

Filter Syntax Example

A value in a field Table/Field eq 'value' Store/Territory eq 'NC'

Multiple values in a field Table/Field in ('value1', Store/Territory in ('NC', 'TN')

'value2')

A distinct value in one field, and Table/Field1 eq 'value1' Store/Territory eq 'NC' and
a different distinct value in and Table/Field2 eq Store/Chain eq 'Fashions Direct'
another field 'value2'
Authentication
You can authenticate using a user (or master user) or a service principal.

Row Level Security (RLS)

With Row Level Security (RLS), you can export a report showing data that's only visible
to certain users. For example, if you're exporting a sales report defined with regional
roles, you can programmatically filter the report so that only a certain region displays.

To export using RLS, you must have the following permissions:

Write and reshare permissions for the semantic model the report is connected to
Workspace member or admin of the workspace where the report resides

Data protection
The .pdf and .pptx formats support sensitivity labels. If you export a report with a
sensitivity label to a .pdf or a .pptx, the exported file displays the report with its
sensitivity label.

A report with a sensitivity label can't be exported to a .pdf or a .pptx using a service
principal.

Localization
When using the exportToFile API, you can pass your desired locale. The localization
settings affect the way the report is displayed, for example by changing formatting
according to the selected local.

Dynamic binding
To export a report while it's connected to a semantic model other then the default
semantic model, specify the required dataset ID in the datasetToBind parameter when
calling the API. Read more about dynamic binding.

Concurrent requests
The exportToFile API supports a limited number of concurrent requests. The maximum
number of concurrent requests supported is 500 per capacity. To avoid exceeding the
limit and getting a Too Many Requests (429) error, either distribute the load over time or
across capacities. Only five pages of a report are processed concurrently. For example, if
you're exporting a report with 50 pages, the export job is processed in 10 sequential
intervals. When optimizing your export job, you may want to consider executing a few
jobs in parallel.

Code examples
When you create an export job, there are four steps to follow:

1. Sending an export request.

2. Polling.
3. Getting the file.
4. Using the file stream.

This section provides examples for each step.

Step 1 - sending an export request

The first step is sending an export request. In this example, an export request is sent for
a specific page.

C#

private async Task<string> PostExportRequest(

Guid reportId,
Guid groupId,
FileFormat format,
IList<string> pageNames = null, /* Get the page names from the GetPages
REST API */
string urlFilter = null)
{
var powerBIReportExportConfiguration = new
PowerBIReportExportConfiguration
{
Settings = new ExportReportSettings
{
Locale = "en-us",
},
// Note that page names differ from the page display names
// To get the page names use the GetPages REST API
Pages = pageNames?.Select(pn => new ExportReportPage(Name =
pn)).ToList(),
// ReportLevelFilters collection needs to be instantiated explicitly
ReportLevelFilters = !string.IsNullOrEmpty(urlFilter) ? new
List<ExportFilter>() { new ExportFilter(urlFilter) } : null,

};
 var exportRequest = new ExportReportRequest
{
Format = format,
PowerBIReportConfiguration = powerBIReportExportConfiguration,
};

// The 'Client' object is an instance of the Power BI .NET SDK

var export = await Client.Reports.ExportToFileInGroupAsync(groupId,
reportId, exportRequest);

// Save the export ID, you'll need it for polling and getting the
exported file
return export.Id;
}

Step 2 - polling
After you send an export request, use polling to identify when the export file you're
waiting for is ready.

C#

private async Task<HttpOperationResponse<Export>> PollExportRequest(

Guid reportId,
Guid groupId,
string exportId /* Get from the PostExportRequest response */,
int timeOutInMinutes,
CancellationToken token)
{
HttpOperationResponse<Export> httpMessage = null;
Export exportStatus = null;
DateTime startTime = DateTime.UtcNow;
const int c_secToMillisec = 1000;
do
{
if (DateTime.UtcNow.Subtract(startTime).TotalMinutes >
timeOutInMinutes || token.IsCancellationRequested)
{
// Error handling for timeout and cancellations
return null;
}

// The 'Client' object is an instance of the Power BI .NET SDK

httpMessage = await
Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId,
reportId, exportId);
exportStatus = httpMessage.Body;

// You can track the export progress using the PercentComplete

that's part of the response
SomeTextBox.Text = string.Format("{0} (Percent Complete : {1}%)",
exportStatus.Status.ToString(), exportStatus.PercentComplete);
 if (exportStatus.Status == ExportState.Running ||
exportStatus.Status == ExportState.NotStarted)
{
// The recommended waiting time between polling requests can be
found in the RetryAfter header
// Note that this header is not always populated
var retryAfter = httpMessage.Response.Headers.RetryAfter;
var retryAfterInSec = retryAfter.Delta.Value.Seconds;
await Task.Delay(retryAfterInSec * c_secToMillisec);
}
}
// While not in a terminal state, keep polling
while (exportStatus.Status != ExportState.Succeeded &&
exportStatus.Status != ExportState.Failed);

return httpMessage;
}

Step 3 - getting the file

Once polling returns a URL, use this example to get the received file.

C#

private async Task<ExportedFile> GetExportedFile(

Guid reportId,
Guid groupId,
Export export /* Get from the PollExportRequest response */)
{
if (export.Status == ExportState.Succeeded)
{
// The 'Client' object is an instance of the Power BI .NET SDK
var fileStream = await
Client.Reports.GetFileOfExportToFileAsync(groupId, reportId, export.Id);
return new ExportedFile
{
FileStream = fileStream,
FileSuffix = export.ResourceFileExtension,
};
}
return null;
}

public class ExportedFile

{
public Stream FileStream;
public string FileSuffix;
}

Step 4 - Using the file stream

When you have the file stream, you can handle it in the way that best fits your needs.
For example, you can email it or use it to download the exported reports.

End-to-end example
This is an end-to-end example for exporting a report. This example includes the
following stages:

1. Sending the export request.

2. Polling.
3. Getting the file.

C#

private async Task<ExportedFile> ExportPowerBIReport(

Guid reportId,
Guid groupId,
FileFormat format,
int pollingtimeOutInMinutes,
CancellationToken token,
IList<string> pageNames = null, /* Get the page names from the GetPages
REST API */
string urlFilter = null)
{
const int c_maxNumberOfRetries = 3; /* Can be set to any desired number
*/
const int c_secToMillisec = 1000;
try
{
Export export = null;
int retryAttempt = 1;
do
{
var exportId = await PostExportRequest(reportId, groupId,
format, pageNames, urlFilter);
var httpMessage = await PollExportRequest(reportId, groupId,
exportId, pollingtimeOutInMinutes, token);
export = httpMessage.Body;
if (export == null)
{
// Error, failure in exporting the report
return null;
}
if (export.Status == ExportState.Failed)
{
// Some failure cases indicate that the system is currently
busy. The entire export operation can be retried after a certain delay
// In such cases the recommended waiting time before
retrying the entire export operation can be found in the RetryAfter header
var retryAfter = httpMessage.Response.Headers.RetryAfter;
if(retryAfter == null)
 {
// Failed state with no RetryAfter header indicates that
the export failed permanently
return null;
}

var retryAfterInSec = retryAfter.Delta.Value.Seconds;

await Task.Delay(retryAfterInSec * c_secToMillisec);
}
}
while (export.Status != ExportState.Succeeded && retryAttempt++ <
c_maxNumberOfRetries);

if (export.Status != ExportState.Succeeded)
{
// Error, failure in exporting the report
return null;
}

var exportedFile = await GetExportedFile(reportId, groupId, export);

// Now you have the exported file stream ready to be used according
to your specific needs
// For example, saving the file can be done as follows:
/*
var pathOnDisk = @"C:\temp\" + export.ReportName +
exportedFile.FileSuffix;

using (var fileStream = File.Create(pathOnDisk))

{
exportedFile.FileStream.CopyTo(fileStream);
}
*/

return exportedFile;
}
catch
{
// Error handling
throw;
}
}

Considerations and limitations

An export API operation load is evaluated as a slow-running background
operation, as described in Premium capacity load evaluation.
All related semantic models in the report you're exporting must reside on a
Premium or Embedded capacity, including semantic models with a Direct Query
connection.
 Exported reports can't exceed a file size of 250 MB.
When exporting to .png, sensitivity labels aren't supported.
The number of exports (single visuals or report pages) that can be included in a
single exported report is 50 (not including exporting paginated reports). If the
request includes more exports, the API returns an error and the export job is
canceled.
Personal bookmarks and persistent filters aren't supported for Power BI report
export to file.
The exportToFile API exports the report with default value if used without
bookmarks or reportLevelFilters.
Exporting a Power BI report that's connected to one or more composite semantic
model, which has at least one external data source with single sign-on (SSO)
enabled, is not supported. When exporting, visuals might not render correctly.
The Power BI visuals listed here aren't supported. When you export a report
containing these visuals, the parts of the report that contain these visuals don't
render, and display an error symbol.
Uncertified Power BI custom visuals
R visuals
PowerApps
Python visuals
Power Automate
Paginated report visual
Visio
ArcGIS visuals

Related content
Review how to embed content for your customers and your organization:

Export paginated report to file

Embed for your customers
Embed for your organization
Export and email a Power BI report with Power Automate

More Questions? Try the Power BI Community

Feedback
Was this page helpful?  Yes  No
Provide product feedback | Ask the community
Export paginated report to file
Article • 05/23/2024

The exportToFile API enables exporting a Power BI paginated report by using a REST
call. The following file formats are supported:

.pptx (PowerPoint)

.pdf (and Accessible PDF, or PDF/UA)

.xlsx (Excel)

.docx (Word)

.csv

.xml

.mhtml

Image
When exporting to an image, set the image format via the OutputFormat format
setting. The supported OutputFormat values are:
.tiff (default)
.bmp
.emf
.gif
.jpeg
.png

Usage examples
You can use the export feature in various ways. Here are a couple of examples:

Send to print button - In your application, create a button that when clicked on
triggers an export job. The job can export the viewed report as a .pdf or a .pptx.
When it's complete, the user can receive the file as a download. Using report
parameters and format settings you can export the report in a specific state,
including filtered data, custom page sizes, and other format-specific settings. As
the API is asynchronous, it may take some time for the file to be available.

Email attachment - Send an automated email at set intervals, with an attached .pdf
report. This scenario can be useful if you want to automate sending a weekly
 report to executives.

Using the API

License requirements
The report you're exporting must reside in a workspace backed by a Premium,
Embedded, or Fabric capacity.
The exportToFile API, has limited support in Premium Per User (PPU).

Rendering events
To make sure the export doesn't begin before the visual finishes rendering, use the
"Rendering" events API and only begin the export when rendering is finished.

Polling
The API is asynchronous. When the exportToFile API is called, it triggers an export job.
After triggering an export job, use polling to track the job, until it's complete.

When the export is complete, the polling API call returns a Power BI URL for getting the
file. The URL is available for 24 hours.

Supported features

Format settings
Specify various format settings for each file format. The supported properties and values
are equivalent to Device Info parameters for paginated report URL parameters.

Here are two examples. The first is for exporting the first four pages of a report using
the report page size to a .pptx file. The second example is for exporting the third page
of a report to a .jpeg file.

Exporting the first four pages to a .pptx

JSON

{
"format": "PPTX",
 "paginatedReportConfiguration":{
"formatSettings":{
"UseReportPageSize": "true",
"StartPage": "1",
"EndPage": "4"
}
}
}

Exporting the third page to a .jpeg

JSON

{
"format": "IMAGE",
"paginatedReportConfiguration":{
"formatSettings":{
"OutputFormat": "JPEG",
"StartPage": "3",
"EndPage": "3"
}
}
}

Report parameters
You can use the exportToFile API to programmatically export a report with a set of
report parameters. This is done using report parameter capabilities.

Here's an example for setting report parameter values.

JSON

{
"format": "PDF",
"paginatedReportConfiguration":{
"parameterValues":[
{"name": "State", "value": "WA"},
{"name": "City", "value": "Seattle"},
{"name": "City", "value": "Bellevue"},
{"name": "City", "value": "Redmond"}
]
}
}

Authentication
You can authenticate using a user (or master user) or a service principal.

Row Level Security (RLS)

When using a Power BI semantic model that has Row Level Security (RLS) defined as a
data source, you can export a report showing data that's only visible to certain users. For
example, if you're exporting a sales report that's defined with regional roles, you can
programmatically filter the report so that only a certain region is displayed.

To export using RLS, you must have read permission for the Power BI semantic model
the report is using as a data source.

Here's an example of supplying an effective user name for RLS.

JSON

{
"format": "PDF",
"paginatedReportConfiguration":{
"identities": [
{"username": "[email protected]"}
]
}
}

Single Sign-on SQL and Dataverse (SSO)

In Power BI, you have the option to set OAuth with SSO. When you do, the credentials
for the user viewing the report are used to retrieve data. The access token in the request
header isn't used to access the data. The token must be passed in with the effective
identity in the post body.

Getting the correct access token for the resource that you want to access can sometimes
be tricky.

For Azure SQL, the resource is https://database.windows.net .

For Dataverse, the resource is the https:// address for your environment. For
example, https://contoso.crm.dynamics.com .

Access the token API using the AuthenticationContext.AcquireTokenAsync method.

Here's an example for supplying an effective identity (user name) with an access token.

JSON
 {
"format":"PDF",
"paginatedReportConfiguration":{
"formatSettings":{
"AccessiblePDF":"true",
"PageHeight":"11in",
"PageWidth":"8.5in",
"MarginBottom":"2in"
},
"identities":[
{
"username":"[email protected]",
"identityBlob": {
"value": "eyJ0eX....full access token"
}
}
]
}
}

Concurrent requests
The exportToFile supports a limited number of concurrent requests. The maximum
number of concurrent paginated report render requests is 500. To avoid exceeding the
limit and getting a Too Many Requests (429) error, either distribute the load over time or
across capacities.

With Premium Per User (PPU), the exportToFile API allows just one request in a five-
minute window. Multiple requests within the five-minute window result in a Too Many
Requests (429) error.

Code examples
The Power BI API SDK used in the code examples can be download here .

When you create an export job, there are three steps to follow:

1. Sending an export request.

2. Polling.
3. Getting the file.

This section provides examples for each step.

Step 1 - sending an export request

The first step is sending an export request. In this example, an export request is sent for
a specific page range, size, and report parameter values.

C#

private async Task<string> PostExportRequest(

Guid reportId,
Guid groupId)
{
// For documentation purposes the export configuration is created in
this method
// Ordinarily, it would be created outside and passed in
var paginatedReportExportConfiguration = new
PaginatedReportExportConfiguration()
{
FormatSettings = new Dictionary<string, string>()
{
{"PageHeight", "14in"},
{"PageWidth", "8.5in" },
{"StartPage", "1"},
{"EndPage", "4"},
},
ParameterValues = new List<ParameterValue>()
{
{ new ParameterValue() {Name = "State", Value = "WA"} },
{ new ParameterValue() {Name = "City", Value = "Redmond"} },
},
};

var exportRequest = new ExportReportRequest

{
Format = FileFormat.PDF,
PaginatedReportExportConfiguration =
paginatedReportExportConfiguration,
};

var export = await Client.Reports.ExportToFileInGroupAsync(groupId,

reportId, exportRequest);

// Save the export ID, you'll need it for polling and getting the
exported file
return export.Id;
}

Step 2 - polling
After you've sent an export request, use polling to identify when the export file you're
waiting for is ready.

C#
 private async Task<Export> PollExportRequest(
Guid reportId,
Guid groupId,
string exportId /* Get from the ExportToAsync response */,
int timeOutInMinutes,
CancellationToken token)
{
Export exportStatus = null;
DateTime startTime = DateTime.UtcNow;
const int secToMillisec = 1000;
do
{
if (DateTime.UtcNow.Subtract(startTime).TotalMinutes >
timeOutInMinutes || token.IsCancellationRequested)
{
// Error handling for timeout and cancellations
return null;
}

var httpMessage =
await
Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId,
reportId, exportId);

exportStatus = httpMessage.Body;
if (exportStatus.Status == ExportState.Running ||
exportStatus.Status == ExportState.NotStarted)
{
// The recommended waiting time between polling requests can be
found in the RetryAfter header
// Note that this header is only populated when the status is
either Running or NotStarted
var retryAfter = httpMessage.Response.Headers.RetryAfter;
var retryAfterInSec = retryAfter.Delta.Value.Seconds;

await Task.Delay(retryAfterInSec * secToMillisec);

}
}
// While not in a terminal state, keep polling
while (exportStatus.Status != ExportState.Succeeded &&
exportStatus.Status != ExportState.Failed);

return exportStatus;
}

Step 3 - getting the file

Once polling returns a URL, use this example to get the received file.

C#
 private async Task<ExportedFile> GetExportedFile(
Guid reportId,
Guid groupId,
Export export /* Get from the GetExportStatusAsync response */)
{
if (export.Status == ExportState.Succeeded)
{
var httpMessage =
await
Client.Reports.GetFileOfExportToFileInGroupWithHttpMessagesAsync(groupId,
reportId, export.Id);

return new ExportedFile

{
FileStream = httpMessage.Body,
ReportName = export.ReportName,
FileExtension = export.ResourceFileExtension,
};
}

return null;
}

public class ExportedFile

{
public Stream FileStream;
public string ReportName;
public string FileExtension;
}

End-to-end example
This is an end-to-end example for exporting a report. This example includes the
following stages:

1. Sending the export request.

2. Polling.
3. Getting the file.

C#

private async Task<ExportedFile> ExportPaginatedReport(

Guid reportId,
Guid groupId,
int pollingtimeOutInMinutes,
CancellationToken token)
{
try
{
var exportId = await PostExportRequest(reportId, groupId);
 var export = await PollExportRequest(reportId, groupId, exportId,
pollingtimeOutInMinutes, token);
if (export == null || export.Status != ExportState.Succeeded)
{
// Error, failure in exporting the report
return null;
}

return await GetExportedFile(reportId, groupId, export);

}
catch
{
// Error handling
throw;
}
}

Considerations and limitations

Exporting a paginated report that has a Power BI semantic model as its data
source, isn't supported in the following cases:
The caller is a service principal profile.
One of the semantic model's data sources is configured with single sign-on
(SSO) enabled and an effective identity was provided.
The Power BI semantic model has DirectQuery to Azure Analysis Services or to
another Power BI semantic model, and an effective identity was provided.

Exporting a paginated report that has Azure Analysis Services data source
configured with single sign-on (SSO) enabled, isn't supported in the following
cases:
The caller is a service principal profile.
The caller is a master user and an effective identity was provided.

To export a paginated report with an effective identity, the username must be an

existing user from your tenant’s Microsoft Entra ID.

Export of a report is limited to 60 minutes, which matches the life of the user
access token. If you get a timeout error past the 60-minute mark when exporting
large amounts of data, consider reducing the amount of data using appropriate
filters.

The file share URL hyperlink (file share /UNC path) doesn't works when exporting a
published paginated report on Power BI service online.
Related content
Review how to embed content for your customers and your organization:

Export report to file

Embed for your customers
Embed for your organization

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Move your embedded app to
production
Article • 01/20/2024

） Important

This article only applies to embed-for-your-customers applications. If you're using

the embed-for-your-organization scenario, you need to use either a Pro or
Premium license.

After you've developed your application, you need to back your workspace with a
capacity before you can move to production. All workspaces (the ones containing the
reports or dashboards, and the ones containing the semantic models) must be assigned
to a capacity.

Create a capacity
By creating a capacity, you can take advantage of having a resource for your customers.
There are two types of capacities you can choose from:

Power BI Premium - A tenant-level Microsoft 365 subscription available in two

SKU families, EM and P. When you embed Power BI content, this solution is
referred to as Power BI embedding. For more information regarding this
subscription, see What is Power BI Premium?.

Azure Power BI Embedded - A subscription that uses A SKUs. You can purchase a
capacity from the Azure portal . For details about how to create a Power BI
Embedded capacity, see Create Power BI Embedded capacity in the Azure portal.

７ Note

SKUs of type A don't support the use of a free Power BI license to access
Power BI content.

Capacity specifications
The following table describes the resources and limits of each SKU. To determine which
capacity best fits your needs, see Which solution should I choose?.
 ﾉ Expand table

SKU Capacity Units (CU) Power BI SKU Power BI v-cores

F2 2 N/A N/A

F4 4 N/A N/A

F8 8 EM1/A1 1

F16 16 EM2/A2 2

F32 32 EM3/A3 4

F64 64 P1/A4 8

F128 128 P2/A5 16

F256 256 P3/A6 32

F5121 512 P4/A7 64

F10241 1,024 P5/A8 128

F20481 2,048 N/A N/A

1
These SKUs aren't available in all regions. To request using these SKUs in regions
where they're not available, contact your Microsoft account manager.

Development testing
For development testing, you can use free embed trial tokens with a Pro license or
Premium Per User (PPU) license. To embed in a production environment, use a capacity.

） Important

Free trial tokens are limited to development testing only. After going to production,
a capacity must be purchased. Until a capacity is purchased, the Free trial version
banner continues to appear at the top of the embedded report.

The number of embed trial tokens a Power BI service principal or master user (master
account) can generate is limited. Use the Available features API to check the percentage
of your current embedded usage. The usage amount is displayed per service principal or
master account.
If you run out of embed tokens while testing, you need to purchase a Power BI
Embedded or Premium capacity. There's no limit to the number of embed tokens you
can generate with a capacity.

Assign a workspace to a capacity

After you create a capacity, you can assign your workspace to that capacity.

Each workspace that contains a Power BI item related to the embedded content
(including semantic models, reports, and dashboards) must be assigned to capacities.
For example, if an embedded report and the semantic model bound to it reside in
different workspaces, both workspaces must be assigned to capacities.

Assign a workspace to a capacity by using a service

principal
To assign a workspace to a capacity by using a service principal, use the Power BI REST
API. When you're using the Power BI REST APIs, make sure to use the service principal
object ID. The service principal should have administrator permissions for the workspace
and capacity assignment permissions for the capacity.

Assign a workspace to a capacity by using a master user

You can also assign a workspace to a capacity from the settings of that workspace by
using a master user. The master user must have admin permissions for that workspace,
and also capacity assignment permissions for that capacity.

1. In the Power BI service, expand Workspaces, and then scroll to the workspace
you're using for embedding your content. On its More menu, select Workspace
settings.

2. Select the Premium tab, and do the following:

a. Under License mode, select the type of capacity you created: Premium per
capacity or Embedded.

b. Select the capacity you created.

c. Select Save.
After you assign your workspace to a capacity, a diamond appears next to it in the
Workspaces list.
Related content
Capacity and SKUs in Power BI embedded analytics
Capacity planning in Power BI embedded analytics
Considerations when generating an embed token

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Capacity and SKUs in Power BI
embedded analytics
Article • 01/30/2024

Power BI embedded analytics requires a capacity (A, EM, P, or F SKU) in order to publish
embedded Power BI content.

Capacity is a dedicated set of resources reserved for exclusive use. It offers dependable,
consistent performance for your content.

７ Note

You need a Power BI Pro or Premium Per User (PPU) account to publish content.
You can publish content without a Pro or PPU license by using a service principal
executing the REST API, Post Import In Group.

What are the different capacities?

Power BI embedded analytics offers two publishing solutions, and Microsoft Fabric
offers a third. Each solution requires different SKUs.

Power BI Embedded

Power BI Premium

Microsoft Fabric

Power BI Embedded
Power BI Embedded is for ISVs and developers who want to embed visuals into their
applications.

Applications using Power BI Embedded allow users to consume content stored on Power
BI Embedded capacity. Power BI Embedded is shipped with an A SKU.

Power BI Premium
Power BI Premium is geared toward enterprises who want a complete BI solution that
provides a single view of its organization, partners, customers, and suppliers.
Power BI Premium is a SaaS product that allows users to consume content through
mobile apps, internally developed apps, or at the Power BI portal (Power BI service). This
service enables Power BI Premium to provide a solution for both internal and external
customer facing applications.

Power BI premium offers two SKUs, P and EM.

Understand the differences between the P and EM SKUs

Buy a Premium SKU

Microsoft Fabric
Microsoft Fabric is an Azure offering that brings together new and existing components
from Power BI, Azure Synapse, and Azure Data Explorer into a single integrated
environment. Fabric uses F SKUs and supports embedding Power BI items. To read more
about F SKUs, see Microsoft Fabric licenses.

Capacity and SKUs

Each capacity offers a selection of SKUs, and each SKU provides different resource tiers
for computing power. The type of SKU you require, depends on the type of solution you
wish to deploy.

To understand which workloads are supported for each tier, refer to the Configure
workloads in a Premium capacity article.

To plan and test your capacity, see Capacity planning.

Which SKU should I use?

The following table provides a summary of features, the capacity they require, and the
specific SKU that is needed for each one.

In this table, a custom app refers to a web app created using embedded analytics. When
you embed to a custom web app as a developer (using the JavaScript or .NET SDKs, or
the REST APIs), you can control and customize the UX. This ability isn't available with
other embedding options, such as Power BI service and Power BI Mobile.

ﾉ Expand table

Scenario Azure Azure Office

(F SKU) (A SKU) (P and EM SKUs)

 Scenario Azure Azure Office
Embed for your customers ✔ ✔ ✔
(app owns data)

Embed for your organization ✔ ✖ ✔

(user owns data)

Microsoft 365 apps ✔ ✖ ✔

(formerly known as Office 365 apps)

Embed in Teams
Embed in SharePoint
Embed in PowerPoint

Secure URL embedding ✔ ✖ ✔

(embed from Power BI service)

７ Note

A Power BI Pro or Premium Per User (PPU) license is needed for publishing
content to a Power BI app workspace.
Only P SKUs and F SKUs equivalent to a F64 SKU or higher, allow free Power
BI users to consume Power BI apps and shared content in Power BI service.
Smaller SKUs require a Pro license to consume Power BI content.
The F SKU is part of Fabric. To read more about F SKUs see Microsoft Fabric
licenses.

Capacity considerations
For development testing, you can use free embed trial tokens with a Pro license. To
embed in a production environment, you must use a capacity.

） Important

Free trial tokens are limited to development testing only. Once going to
production, a capacity must be purchased. Until a capacity is purchased, the Free
trial version banner will continue to appear at the top of the embedded report.

The following table lists payment and usage considerations per capacity.

ﾉ Expand table
 Payment and Power BI Power BI Premium Power BI Premium
usage Embedded

Offer Azure Office Office

SKU A EM P

Billing Hourly Monthly Monthly

Commitment None Yearly Monthly or yearly

Usage Azure resources Embed in apps, and in Embed in apps, and in

can be: Microsoft applications Power BI service
Scaled up or
down
Paused and
resumed

SKU computing power

The following table describes the resources of each Power BI SKU.

ﾉ Expand table

SKU Capacity Units (CU) Power BI SKU Power BI v-cores

F2 2 N/A N/A

F4 4 N/A N/A

F8 8 EM1/A1 1

F16 16 EM2/A2 2

F32 32 EM3/A3 4

F64 64 P1/A4 8

F128 128 P2/A5 16

F256 256 P3/A6 32

F5121 512 P4/A7 64

F10241 1,024 P5/A8 128

F20481 2,048 N/A N/A

1
These SKUs aren't available in all regions. To request using these SKUs in regions
where they're not available, contact your Microsoft account manager.
More information about SKU limits, is available here:

F SKUs - Microsoft Fabric licenses.

SKU limits in Power BI - What is Power BI Premium?

Power BI interactive (not paginated) reports - Export Power BI report to file.

Embedded memory enhancements

The amount of memory available on each node size is described in the Max memory
(GB) column in the Semantic model SKU limitation table. It's set to the memory footprint
limit of a single Power BI item (such as a semantic model, report or dashboard), and not
to the cumulative consumption of memory. For example, in an F64 capacity, a single
dataset size is limited to 25 GB.

Related content
Embed for your customers
Embed for your organization
Embed from apps
Capacity planning in Power BI
embedded analytics
Article • 01/12/2024

Calculating the type of capacity you need for a Power BI embedded analytics
deployment can be complicated. The capacity you need depends on several parameters,
some of which are hard to predict.

Some of the things to consider when planning your capacity are:

The data models you're using.

The number and complexity of required queries.
The hourly distribution of your application usage.
Data refresh rates.
Other usage patterns that are hard to predict.

７ Note

This article explains how to plan what capacity you need and how to do a load
testing assessment for Power BI embedded analytics A-SKUs.

When planning your capacity, take the following steps:

1. Optimize your performance and resource consumption.

2. Determine your minimum SKU.
3. Assess your capacity load.
4. Set up your capacity autoscale.

Optimize your performance and resource

consumption
Before you start any capacity planning or load testing assessment, optimize the
performance and resource consumption (especially the memory footprint) of your
reports and semantic models.

To optimize your performance, follow the guidelines in the following resources:

Optimization guide for Power BI

Best practices for faster performance in Power BI embedded analytics
For a detailed tutorial on optimizing performance, see the Optimize a model for
performance in Power BI training module.

Determine your minimum SKU

The following table summarizes all the limitations that are dependent on the capacity
size. To determine the minimum SKU for your capacity, check the Max memory (GB)
column under the Semantic model header. Also, keep in mind the current limitations.

ﾉ Expand table

SKU Capacity Units (CU) Power BI SKU Power BI v-cores

F2 2 N/A N/A

F4 4 N/A N/A

F8 8 EM1/A1 1

F16 16 EM2/A2 2

F32 32 EM3/A3 4

F64 64 P1/A4 8

F128 128 P2/A5 16

F256 256 P3/A6 32

F5121 512 P4/A7 64

F10241 1,024 P5/A8 128

F20481 2,048 N/A N/A

1
These SKUs aren't available in all regions. To request using these SKUs in regions
where they're not available, contact your Microsoft account manager.

Assess your capacity load

To test or assess your capacity load:

1. Create a Premium Power BI Embedded capacity in Azure for the testing. Use a
subscription associated with the same Microsoft Entra tenant as your Power BI
tenant and a user account that's signed in to that same tenant.​
 2. Assign the workspace (or workspaces) you'll use to test to the Premium capacity
you created. You can assign a workspace in one of the following ways:

Programmatically with the Groups AssignToCapacity API. Check the

assignment status with the Groups CapacityAssignmentStatus API or via a
PowerShell script. For sample code, see the AssignWorkspacesToCapacity
function in the Zero-Downtime-Capacity-Scale sample on GitHub .
Manually as a workspace admin or via the Admin portal as a capacity admin.
For more information, see Assign a workspace to a capacity by using a master
user.

3. As the capacity admin, install the Microsoft Fabric Capacity Metrics app. Provide
the capacity ID and time (in days) to monitor, and then refresh the data.

4. Use the Power BI Capacity Load Assessment Tool to assess your capacity needs.
This GitHub repository also includes a video walk-through . Use this tool
carefully: test with up to a few dozen concurrent simulated users and extrapolate
for higher concurrent loads (hundreds or thousands, depending on your needs.)
For more information, see Assess your capacity load. Alternatively, use other load
testing tools, but treat the iFrame as a black box and simulate user activity via
JavaScript code.

5. Use the Microsoft Fabric Capacity Metrics app that you​installed in step 3 to
monitor the capacity utilization incurred via the load testing tool. Alternatively, you
can monitor the capacity by checking the Premium metrics by using alerts in Azure
Monitor.

Consider using a larger SKU for your capacity if the actual CPU incurred on your capacity
by the load testing is approaching the capacity limit.

Set up autoscale
You can use the following autoscaling technique to elastically resize your A-SKU capacity
to address its current memory and CPU needs.

Use the Capacities Update API to scale the capacity SKU up or down. To see how to
use the API to create your own scripts for scaling up and down, see a runbook
PowerShell script capacity scale-up sample .

Use Monitor alerts to track the following Power BI Embedded capacity metrics:
Overload (1 if your capacity's CPU has surpassed 100 percent and is in an
overloaded state, otherwise 0)
CPU (percentage of CPU utilization)
 CPU Per Workload if specific workloads (like paginated reports) are used

Configure the Monitor alerts so that when these metrics hit the specified values, a
script run is triggered that scales the capacity up or down.

For example, you can create a rule that invokes the scale-up capacity runbook to update
the capacity to a higher SKU if the overload is 1 or if the CPU value is 95 percent. You
can also create a rule that invokes a scale-down capacity runbook script to update the
capacity to a lower SKU if the CPU value drops below 45 or 50 percent.

You can also invoke scale-up and scale-down runbooks programmatically on demand
before and after a semantic model is refreshed. This approach ensures your capacity has
enough RAM (GB) for large semantic models that use that capacity.

Related content
Capacity and SKUs in Power BI embedded analytics
Power BI Embedded performance best practices

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Create Power BI Embedded capacity in
the Azure portal
Article • 05/13/2024

This article walks you through how to create a Power BI Embedded capacity in Microsoft
Azure. Power BI Embedded simplifies Power BI capabilities by helping you quickly add
stunning visuals, reports, and dashboards to your apps.

Prerequisites
Before you can create a capacity, you need the following:

1. An Microsoft Entra ID: Your subscription must be associated with a Microsoft Entra
organizational tenant. Also, you need to be signed in to Azure with an account in
that tenant. Microsoft personal accounts aren't supported. To learn more, see
Authentication and user permissions.

2. A Power BI tenant: At least one account in your Microsoft Entra tenant must be
signed up for Power BI. Sign into Power BI from that account.

3. Azure subscription: Visit Azure Free Trial to create an account, if you don't
already have one.

4. Resource group: Use a resource group you already have or create a new one.

Create a capacity

７ Note

To create or manage a capacity, you must have the built-in role of contributor or
higher.

Before creating a Power BI Embedded capacity, make sure you're signed into Power BI at
least once.

Portal

1. Sign into the Azure portal .

2. Under Azure services, select Power BI Embedded.

3. Within Power BI Embedded, select Create.

4. Fill in the required information and then select Review + Create.

Subscription - The subscription you would like to create the capacity

against.

Resource group - The resource group that contains this new capacity.
Pick from an existing resource group, or create another. For more
information, see Azure Resource Manager overview.

Resource name - The resource name of the capacity.

Location - The location where Power BI is hosted for your tenant. Your
default location is your home region, but you can change the location
using Multi-Geo options.

Size - The A SKU you require. For more information, see SKU memory
and computing power.

Power BI capacity administrator - An admin for the capacity.

 ７ Note
By default, the capacity administrator is the user creating the
capacity.
You can select a different user or service principal, as capacity
administrator.
The capacity administrator must belong to the tenant where the
capacity is provisioned. Business to business (B2B) users cannot
be capacity administrators.

Considerations and limitations

Your subscription must be associated with a Microsoft Entra organizational account.
Microsoft personal accounts aren't supported

Related content
Manage capacities
Pause and start your Power BI Embedded capacity in the Azure portal
Embed Power BI content into an application for your customers

More questions? Try asking the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Multi-Geo support for Power BI
Embedded
Article • 06/03/2024

Multi-Geo support for Power BI Embedded means that independent software vendors
(ISVs) and organizations that build applications using Power BI Embedded to embed
analytics into their apps can now deploy their data in different regions around the world.

Now, customers using Power BI Embedded can set up an A capacity using Multi-Geo
options, based on the same features and limitations that Power BI Premium supports
using Multi-Geo.

Creating new Power BI Embedded Capacity

resource with Multi-Geo
In the Create resource screen, choose the location of your capacity. Previously, the
location was limited to the location of your Power BI tenant, so only a single location
was available. With Multi-Geo, you can choose between different regions to deploy your
capacity.
Notice that when you open the location drop-down menu, your home tenant is the
default selection.
When you choose a location other than the default tenant location, a message prompts
you to make sure you're aware of the selection.

View Capacity location

You can see your capacities' locations easily from the main Power BI Embedded
management page in the Azure portal.
 

The locations are also available in the Admin portal at PowerBI.com . In the Admin portal,
choose Capacity settings, and then switch to the Power BI Embedded tab.

Learn more about creating capacities with Power BI Embedded.

Manage existing capacities location

You can't change a Power BI Embedded resource location after you've created a new
capacity.

To move your Power BI content to a different region, follow these steps:

1. Create a new capacity in a different region.

2. Assign all workspaces from the existing capacity to the new capacity.

3. Delete or pause the old capacity.

It's important to note that if you decide to delete a capacity without reassigning its
content, all the content in that capacity moves to a shared capacity in your home region.

API support for Multi-Geo

To manage capacities with Multi-Geo through APIs, use the following APIs:

1. Get Capacities - The API returns a list of capacities with access to the user. The
response includes a property called region that specifies the capacity's location.

2. Assign To Capacity - The API allows you to assign a workspace to a capacity

outside of your home region, or to move workspaces between capacities in
different regions. To perform this operation, the user or service principal needs
admin permissions on the workspace, and admin or assign permissions on the
target capacity.
 3. Azure Resource Manager API - all of the Azure Resource Manager API operations,
including Create and Delete, supports Multi-Geo.

Considerations and limitations

The Power BI Embedded multi-geo limitations are similar to the Power BI Premium
multi-geo considerations and limitations.

Related content
What is Power BI Embedded?

Create a Power BI Embedded capacity

Multi-Geo in Power BI Premium capacities

More questions? Ask the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Assess your capacity load
Article • 06/04/2024

This article explains how to simplify capacity planning for Power BI embedded analytics
by using the Power BI Capacity Load Assessment Tool , created for automating load
testing for Power BI embedded analytics capacities (A, EM or P SKUs).

Load assessment tool

The Power BI Capacity Load Assessment Tool can be used to for simulating interactive
Power BI report traffic. It uses PowerShell to create automated load tests against your
capacities, and lets you choose which reports to test, and how many concurrent users to
simulate.

The tool generates load on a capacity by continuously rendering each report with new
filter values (to prevent unrealistically good performance due to report caching), until
the token required for authenticating the tool against the service, expires.

Run the tool

When running the tool, keep in mind the existing load on your capacities and make sure
not to run load tests during top usage times.

Here are some examples of how you can use the planning tool.

Capacity administrators can get a better understanding of how many users their
capacity can handle in a given time frame.
Report authors can understand the user load effect, as measured with the Power BI
desktop's Performance Analyzer.
You can see renders happening in real time on your browser.
Using SQL Server Profiler, you can connect to the XMLA endpoints of the
capacities being measured, to see the queries being executed.
See the load test effects in the premium capacity metrics app's Datasets page.
Capacity admins can use this tool to generate load, and see how that load shows
up.

Review the test results

Review the results of your load assessment using the Microsoft Fabric Capacity Metrics
app.
Power BI capacity tools GitHub repository
The Power BI capacity tools GitHub repository was created to host the capacity
planning tool and other future tools and utilities.

The repository is open source. Users are encouraged to contribute by adding more tools
related to Power BI Premium and Embedded capacities, and improving the existing
ones.

Related content
Capacity and SKUs in Power BI embedded analytics
Power BI Embedded performance best practices

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Scale your Power BI Embedded capacity
in the Azure portal
Article • 06/03/2024

This article walks through how to scale a Power BI Embedded capacity in Microsoft
Azure. Scaling allows you to increase or decrease the size of your capacity.

This assumes you created a Power BI Embedded capacity (A SKU). If you haven't, see
Create Power BI Embedded capacity in the Azure portal to get started.

７ Note

This article describes the process for vertically scaling A SKUs. It doesn't talk about
horizontal scaling or P SKUs.

Scale a capacity
1. Sign into the Azure portal .

2. Under Azure services, select Power BI Embedded to see your capacities.

3. Select the capacity you want to scale. Notice that the current scale for each
capacity is listed under SKU.
 When you make your selection, information about that capacity is displayed next
to it. This information again includes the current scaling under SKU.

4. Under Scale, select Change size.

5. Select a scale and click Resize.
 6. Confirm your tier by viewing the overview tab. The current pricing tier is listed.

Autoscale your capacity

Use one of the autoscaling techniques described here to elastically resize your capacity
and address its memory and CPU needs.

Power BI Embedded Azure Resource Manager REST APIs, for example Capacities -
Update. See this runbook PowerShell script capacity scale-up sample on how to
use this API call can create your own versions of upscale and down-scale scripts.

Use Azure alerts to track Power BI capacity metrics such as:

Overload - 1 if capacity's CPU surpassed 100% and is in an overloaded state.
Otherwise, 0.
CPU utilization in percentage
CPU Per Workload if specific workloads are used, such as paginated reports
 When these metrics reach the value specified in the Azure Monitor Alert rules, the
rule will trigger an upscale or downscale runbook script.

For example, you can create a rule that if Overload = 1 or if CPU = 95%, then the
upscale capacity runbook script will be invoked to update the capacity to a higher
SKU.
You can also create a rule that if the CPU drops below 50%, a down-scale runbook
script will be invoked to update the capacity to a lower CPU.
Use the Power BI Embedded sample script as a reference for scaling a capacity.

Considerations and limitations

Scaling capacities may involve a small amount of downtime.

Related content
Pause and start your Power BI Embedded capacity in the Azure portal
How to embed your Power BI dashboards, reports, and tiles .

More questions? Try asking the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Pause and start your Power BI
Embedded capacity in the Azure portal
Article • 06/03/2024

This article walks through how to pause and start a Power BI Embedded capacity in
Microsoft Azure. This article assumes you have a Power BI Embedded capacity. If you
haven't, see Create Power BI Embedded capacity in the Azure portal to get started.

If you don't have an Azure subscription, create a free account before you begin.

Pause your capacity

Pausing your capacity prevents you from being billed. Pausing your capacity is great if
you don't need to use the capacity for some time. Use the following steps to pause your
capacity.

７ Note

Pausing a capacity can prevent content from being available within Power BI. Make
sure to unassign workspaces from your capacity before pausing the capacity to
prevent workspace interruption.

1. Sign into the Azure portal .

2. Under Azure services, select Power BI Embedded to see your capacities.

3. Select the capacity you want to pause.

 4. Select Pause above the capacity details.

5. Select Yes to confirm you want to pause the capacity.

Start your capacity

Resume usage by starting your capacity. Starting your capacity also resumes billing.
1. Sign into the Azure portal .

2. Select All services > Power BI Embedded to see your capacities.

3. Select the capacity you want to start.

4. Select Start above the capacity details.

5. Select Yes to confirm you want to start the capacity.

If any content is assigned to this capacity, the content becomes available once the
capacity is started.

Use CLI to start or pause your capacity

You can also start or pause your capacity from the command line using:

Azure Resource Manager API references

PowerShell references
Suspend
Resume

Related content
Scale your Power BI Embedded capacity .

How to embed your Power BI dashboards, reports and tiles .

More questions? Try asking the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Service principal profiles for
multitenancy apps in Power BI
Embedded
Article • 11/10/2023

This article explains how an ISV or any other Power BI Embedded app owner with many
customers can use service principal profiles to map and manage each customer's data
as part of their Power BI embed for your customers solution. Service principal profiles
allow the ISV to build scalable applications that enable better customer data isolation
and establish tighter security boundaries between customers. This article discusses the
advantages and the limitations of this solution.

７ Note

The word tenant in Power BI can sometimes refer to an Azure AD tenant. In this
article, however, we use the term multitenancy to describe a solution where a single
instance of a software application serves multiple customers or organizations
(tenants) requiring physical and logical separation of data. . For example, the Power
BI app builder can allocate a separate workspace for each if its customers (or
tenants) as we show below. These customers are not necessarily Azure AD tenants,
so don’t confuse the term multitenant application that we use here, with the Azure
AD multitenant application.

A service principal profile is a profile created by a service principal. The ISV app calls the
Power BI APIs using a service principal profile, as explained in this article.

The ISV application service principal creates a different Power BI profile for each
customer, or tenant. When a customer visits the ISV app, the app uses the
corresponding profile to generate an embed token that will be used to render a report
in the browser.

Using service principal profiles enables the ISV app to host multiple customers on a
single Power BI tenant. Each profile represents one customer in Power BI. In other words,
each profile creates and manages Power BI content for one specific customer's data.
 ７ Note

This article is aimed at organizations that want to set up a multitenant app using
service principal profiles. If your organization already has an app that supports
multitenancy, and you want to migrate to the service principal profile model, see
Migrate to the service principal profiles model.

Setting up your Power BI content involves the following steps:

Create a profile
Set the profile permissions
Create a workspace for each customer
Import reports and semantic models into the workspace
Set the semantic model connection details to connect to the customer's data
Remove permissions from the service principal (optional, but helps with scalability)
Embed a report into the application

All the above steps can be fully automated using Power BI REST APIs.

Prerequisites
Before you can create service principal profiles, you need to:

Set up the service principal by following the first three steps of Embed Power BI
content with service principal.
 From a Power BI tenant admin account, enable creating profiles in the tenant using
the same security group you used when you created the service principal.

Create a profile
Profiles can be created, updated, and deleted using Profiles REST API.

For example, to create a profile:

HTTP

POST https://api.powerbi.com/v1.0/myorg/profiles HTTP/1.1

Authorization: Bearer eyJ0eXAiOiJK…UUPA
Content-Type: application/json; charset=utf-8

{"displayName":"ContosoProfile"}

A service principal can also call GET Profiles REST API to get a list of its profiles. For
example:

HTTP

GET https://api.powerbi.com/v1.0/myorg/profiles HTTP/1.1

Authorization: Bearer eyJ0eXA…UUPA
Profile permissions
Any API that grants a user permission to Power BI items can also grant a profile
permission to Power BI items. For example, Add Group User API can be used to grant a
profile permission to a workspace.

The following points are important to understand when using profiles:

A profile belongs to the service principal that created it, and can only be used by
that service principal.
A profile owner can't be changed after creation.
A profile isn't a standalone identity. It needs the service principal Azure AD token
to call Power BI REST APIs.

ISV apps call Power BI REST APIs by providing the service principal Azure AD token in
the Authorization header, and the profile ID in the X-PowerBI-Profile-Id header. For
example:

HTTP

GET https://api.powerbi.com/v1.0/myorg/groups HTTP/1.1

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz.....SXBwasfg
X-PowerBI-Profile-Id: 5f1aa5ed-5983-46b5-bd05-999581d361a5

Create a workspace
Power BI workspaces are used to host Power BI items such as reports and semantic
models.

Each profile needs to:

Create at least one Power BI workspace

HTTP

POST https://api.powerbi.com/v1.0/myorg/groups HTTP/1.1

Authorization: Bearer eyJ0eXA…ZUiIsg
Content-Type: application/json; charset=utf-8
X-PowerBI-Profile-Id: a4df5235-6f18-4141-9e99-0c3512f41306

{
"name": "ContosoWorkspace"
}
 Grant access permissions to the workspace. The service principal profile must have
Admin access to the workspace.

Assign the workspace to a capacity

HTTP

POST https://api.powerbi.com/v1.0/myorg/groups/f313e682-c86b-422c-a3e2-
b1a05426c4a3/AssignToCapacity HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK…wNkZUiIsg
Content-Type: application/json; charset=utf-8
X-PowerBI-Profile-Id: a4df5235-6f18-4141-9e99-0c3512f41306

{
"capacityId": "13f73071-d6d3-4d44-b9de-34590f3e3cf6"
}

Read more about Power BI workspaces.

Import reports and semantic models

Use Power BI Desktop to prepare reports that are connected to the customer's data or
sample data. Then, you can use the Import API to import the content into the created
workspace.

HTTP

POST https://api.powerbi.com/v1.0/myorg/groups/f313e682-c86b-422c-a3e2-
b1a05426c4a3/imports?datasetDisplayName=ContosoSales HTTP/1.1
Authorization: Bearer eyJ...kZUiIsg
Content-Type: multipart/form-data; boundary="8b071895-b380-4769-9c62-
7e586d717ed7"
X-PowerBI-Profile-Id: a4df5235-6f18-4141-9e99-0c3512f41306
Fiddler-Encoding: base64

LS04YjA3MTg5NS1iMzgwLTQ3...Tg2ZDcxN2VkNy0tDQo=

Use dataset parameters to create a semantic model that can connect to different
customers' data sources. Then, use the Update parameters API to define which
customers' data the semantic model connects to.

Set the semantic model connection

ISVs usually store their customers' data in one of two ways:
 A separate database for each customer
A single multitenant database

In either case, you should end up with single-tenant semantic models (one semantic
model per customer) in Power BI.

A separate database for each customer

If the ISV application has a separate database for each customer, create single-tenant
semantic models in Power BI. Provide each semantic model with connection details that
point to its matching database. Use one of the following methods to avoid creating
multiple identical reports with different connection details:

Semantic model parameters: Create a semantic model with parameters in the

connection details (such as SQL server name, SQL database name). Then, import a
report into a customer's workspace and change the parameters to match the
customer's database details.

Update Datasource API: Create a .pbix that points to a data source with sample
content. Then, import the .pbix into a customer's workspace and change the
connection details using the Update Datasource API.

A single multitenant database

If the ISV application uses one database for all its customers, separate the customers
into different semantic models in Power BI as follows:

Create a report using parameters that only retrieve the relevant customer's data. Then,
import a report into a customer's workspace and change the parameters to retrieve the
relevant customer's data only.

Embed a report
After the setup is complete, you can embed customer reports and other items into your
application using an embed token.

When a customer visits your application, use the corresponding profile to call the
GenerateToken API. Use the generated embed token to embed a report or other items
in the customer's browser.

To generate an embed token:

 HTTP

POST https://api.powerbi.com/v1.0/myorg/GenerateToken HTTP/1.1

Authorization: Bearer eyJ0eXAiOi…kZUiIsg
Content-Type: application/json; charset=utf-8
X-PowerBI-Profile-Id: a4df5235-6f18-4141-9e99-0c3512f41306

{
"datasets": [
{
"id": "3b1c8f74-fbbe-45e0-bf9d-19fce69262e3"
}
],
"reports": [
{
"id": "3d474b89-f2d5-43a2-a436-d24a6eb2dc8f"
}
]
}

Design aspects
Before setting up a profile-based multitenant solution, you should be aware of the
following issues:

Scalability
Automation & operational complexity
Multi-Geo needs
Cost efficiency
Row level security

Scalability
By separating the data into separate semantic models for each customer, you minimize
the need for large semantic models. When the capacity gets overloaded, it can evict
unused semantic models to free memory for active semantic models. This optimization
is impossible for a single large semantic model. By using multiple semantic models, you
can also separate tenants into multiple Power BI capacities if necessary.

Without profiles, a service principal is limited to 1,000 workspaces. To overcome this

limit, a service principal can create multiple profiles, where each profile can create up to
1,000 workspaces. With multiple profiles, the ISV app can isolate each customer's
content using distinct logical containers.
Once a service principal profile has access to a workspace, its parent service principal’s
access to the workspace can be removed to avoid scalability problems.

Even with these advantages, you should consider the potential scale of your application.
For example, the number of workspace items a profile can access is limited. Today, a
profile has the same limits as a regular user. If the ISV application allows end users to
save a personalized copy of their embedded reports, a customer's profile will have
access to all the created reports of all its users. This model can eventually exceed the
limit.

Automation and operational complexity

With Power BI profile-based separation, you might need to manage hundreds or
thousands of items. Therefore, it's important to define the processes that frequently
happen in your application lifecycle management, and ensure you have the right set of
tools to do these operations at scale. Some of these operations include:

Adding a new tenant

Updating a report for some or all tenants
Updating the semantic model schema for some or all tenants
Unplanned customizations for specific tenants
Frequency of semantic model refreshes

For example, creating a profile and a workspace for a new tenant is a common task,
which can be fully automated with the Power BI REST API.

Multi-Geo needs
Multi-Geo support for Power BI Embedded means that ISVs and organizations that build
applications using Power BI Embedded to embed analytics into their apps can now
deploy their data in different regions around the world. To support different customers
in different regions, assign the customer's workspace to a capacity in the desired region.
This task is a simple operation that doesn't involve extra cost. However, if you have
customers that need data from multiple regions, the tenant profile should duplicate all
items into multiple workspaces that are assigned to different regional capacities. This
duplication may increase both cost and management complexity.

For compliance reasons, you may still want to create multiple Power BI tenants in
different regions. Read more about multi-geo.

Cost efficiency
Application developers using Power BI Embedded need to purchase a Power BI
Embedded capacity. The profile-based separation model works well with capacities
because:

The smallest object you can independently assign to a capacity is a workspace (you
can't assign a report, for example). By separating customers by profiles, you get
different workspaces - one per customer. This way, you get full flexibility to
manage each customer according to their performance needs, and optimize
capacity utilization by scaling up or down. For example, you can manage large and
essential customers with high volume and volatility in a separate capacity to ensure
a consistent level of service, while grouping smaller customers in another capacity
to optimize costs.

Separating workspaces also means separating semantic models between tenants

so that data models are in smaller chunks, rather than a single large semantic
model. These smaller models enable the capacity to manage memory usage more
efficiently. Small, unused semantic models can be evicted after a period of
inactivity, in order to maintain good performance.

When buying a capacity, consider the limit on the number of parallel refreshes, as
refresh processes might need extra capacity when you have multiple semantic models.

Row Level Security

This article explains how to use profiles to create a separate semantic model for each
customer. Alternatively, ISV applications can store all their customers' data in one large
semantic model and use Row-level security (RLS) to protect each customer's data. This
approach can be convenient for ISVs that have relatively few customers and small to
medium-sized semantic models because:

There's only one report and one semantic model to maintain

The onboarding process for new customers can be simplified

Before using RLS, however, make sure you understand its limitations. All the data for all
customers are in one large Power BI semantic model. This semantic model runs in a
single capacity with its own scaling and other limitations.

Even if you use service principal profiles to separate your customers' data, you can still
use RLS within a single customer's semantic model to give different groups access to
different parts of the data. For example, you could use RLS to prevent members of one
department from accessing data of another department in the same organization.
Considerations and limitations
Service Principal Profiles are only supported through the Power BI REST API and
the Power BI .NET SDK . Service Principal Profiles are not supported in Power BI
through the XMLA endpoint or the Tabular Object Model (TOM).
Service principal profiles aren't supported with Azure Analysis Services (AAS) in live
connection mode.

Power BI capacity limitations

Each capacity can only use its allocated memory and V-cores, according to the SKU
purchased. For the recommended semantic model size for each SKU, reference
Premium large semantic models.
To use a semantic model larger than 10 GB, use a Premium capacity and enable the
Large semantic models setting.
For the number of refreshes that can run concurrently on a capacity, reference
resource management and optimization.

Manage service principals

Change a service principal

In Power BI, a profile belongs to the service principal that created it. That means, a
profile can't be shared with other principals. With this limitation, if you want to change
the service principal for any reason, you'll need to recreate all the profiles and provide
the new profiles access to the relevant workspaces. Often, the ISV application needs to
save a mapping between a profile ID and a customer ID in order to pick the right profile
when needed. If you change the service principal and recreate the profiles, the IDs will
also change, and you may need to update the mapping in the ISV application database.

Delete a service principal

２ Warning

Be very careful when deleting a service principal. You don't want to accidentally
lose data from all its associated profiles.

If you delete the service principal in the active directory, all its profiles in Power BI will be
deleted. However, Power BI won't delete the content immediately, so the tenant admin
can still access the workspaces. Be careful when deleting a service principal used in a
production system, especially when you created profiles using this service principal in
Power BI. If you do delete a service principal that has created profiles, be aware that
you'll need to recreate all the profiles, provide the new profiles access to the relevant
workspaces, and update the profile IDs in the ISV application database.

Data separation
When data is separated by service principal profiles, a simple mapping between a profile
and customer prevents one customer from seeing another customer's content. Using a
single service principal requires that the service principal has access to all the different
workspaces in all the profiles.

To add extra separation, assign a separate service principal to each tenant, instead of
having a single service principal access multiple workspaces using different profiles.
Assigning separate service principals has several advantages, including:

Human error or a credential leak won't cause multiple tenants' data to be exposed.
Certificate rotation can be done separately for each tenant.

However, using multiple service principals comes with a high management cost. Select
this path only if you need the extra separation. Keep in mind that the configuration of
which data to show an end user is defined when you generate the embed token, a
backend-only process that end users can't see or change. Requesting an embed token
using a tenant-specific profile will generate an embed token for that specific profile,
which will give you customer separation in consumption.

One report, multiple semantic models

Generally, you have one report and one semantic model per tenant. If you have
hundreds of reports, you'll have hundreds of semantic models. Sometimes, you might
have one report format, with different semantic models (for example, different
parameters or connection details). Each time you have a new version of the report, you'll
need to update all the reports for all tenants. Although you can automate this, it's easier
to manage if you have just one copy of the report. Create a workspace that contains the
report to embed. During a session runtime, bind the report to the tenant-specific
semantic model. Read dynamic bindings for more details.

Customizing and authoring content

When you create content, carefully consider who has permission to edit it. If you allow
multiple users in each tenant to edit, it's easy to exceed semantic model limitations. If
you decide to give users editing capability, monitor their content generation closely, and
scale up as needed. For the same reason, we don't recommend using this capability for
content personalization, where each user can make small changes to a report and save it
for themselves. If the ISV application allows content personalization, consider
introducing workspace retention policies for user-specific content. Retention policies
make it easier to delete content when users move to a new position, leave the company,
or stop using the platform.

System-Managed identity

Instead of a service principal, you can use a user-assigned or system-assignedmanaged

identity to create profiles. Managed identities reduce the need for secrets and
certificates.

Be careful when using a system-managed identity because:

If a system-assigned managed identity is accidentally turned off, you'll lose access

to the profiles. This situation is similar to a case where a service principal is deleted.
A system-assigned managed identity is connected to a resource in Azure (web
app). If you delete the resource, the identity will be deleted.
Using multiple resources (different web apps in different regions) will result in
multiple identities that need to be managed separately (each identity will have its
own profiles).

Due to the above considerations, we recommend that you use a user-assigned managed
identity.

Example
For an example of how to use service principal profiles to manage a multitenant
environment with Power BI and App-Owns-Data embedding, download the App owns
data multitenant repository from Power BI Dev Camp (third party site).

Next steps
Use the Power BI SDK with service principals
Migrate multitenancy apps to the service principal profiles model
Develop scalable multitenancy applications with Power BI embedding
Use the Power BI SDK with service
principal profiles
Article • 03/07/2023

This article explains how to use the SDK with service principal profiles. There are two
ways to connect a Power BI client to a service principal profile. You can:

Create a client with a profile object ID

Specify the profile ID in the API request call

Once the client is associated with a profile, you can get the current service principal
profile from the Power BI client.

Create a Power BI client with a service principal

profile
C#

var profileObjectId = new Guid("81f24a6d-7ebb-4478-99c7-2c36f7870a26");

var powerBIclient = new PowerBIClient(credentials, profileObjectId:
profileObjectId);

When you create a Power BI client with the profile object ID, every API call that uses the
client has the X-PowerBI-profile-id in the request header.

For example:

HTTP

GET https://powerbiapi.analysis-df.windows.net/v1.0/myorg/groups

Authorization: Bearer eyJ0eXAiO.....5U_g

X-PowerBI-profile-id: 81f24a6d-7ebb-4478-99c7-2c36f7870a26

Set profile on API request call

Alternatively, you can specify the profile ID in the API request by using the
customHeaders property in the API's overloaded PowerBIClient method

WithHttpMessagesAsync .
 C#

var powerBIclient = new PowerBIClient(credentials);

var profileHeader = new Dictionary<string, List<string>>();
profileHeader.Add("X-PowerBI-profile-id", new List<string> { "81f24a6d-7ebb-
4478-99c7-2c36f7870a26" });
var groups = await
powerBIclient.Groups.GetGroupsWithHttpMessagesAsync(customHeaders:
profileHeader);

For example,

HTTP

GET https://powerbiapi.analysis-df.windows.net/v1.0/myorg/groups

Authorization: Bearer eyJ0eXAiO.....5U_g

X-PowerBI-profile-id: 81f24a6d-7ebb-4478-99c7-2c36f7870a26

In the preceding code sample, the profile header isn't part of the client default headers,
because the code doesn't add the profile header. You need to specify the profile header
with every API request.

Make sure you avoid duplications. For example, creating a client with a profile object ID
and then specifying the header with the API request results in unauthorized errors.

Get the current service principal profile from

Power BI client
To retrieve the current service principal profile from the SDK client, call
GetServicePrincipalProfileObjectId .

C#

var profileObjectId = new Guid("81f24a6d-7ebb-4478-99c7-2c36f7870a26");

var powerBIclient = new PowerBIClient(credentials, profileObjectId:
profileObjectId);
var currentProfileObjectId =
powerBIclient.GetServicePrincipalProfileObjectId();

Considerations and limitations

There's no support for service principal profiles with Azure Analysis Services (AAS) in live
connection mode.

Next steps
Service principal profiles in Power BI Embedded
Migrate multi-customer applications to
the service principal profiles model
Article • 06/04/2024

This article describes how you can get better scalability by migrating your Power BI
embedded analytics multi-customer apps to the service principal profiles model.

Service principal profiles make it easier to manage organizational content in Power BI

and use your capacities more efficiently.

７ Note

This article is aimed at organizations that already have an app that supports
multiple customers from a single Power BI tenant.

Not all apps benefit from the service principal model. For example, the following
apps shouldn't migrate:

Small apps that maintain one service principal with a small number of objects.
Apps that use one multiple service principal per customer

Prerequisites
It's important to read about service principal profiles before you start the migration.

You also need to do the following steps:

Set up the service principal by following the first three steps of Embed Power BI
content with service principal.
From a Power BI tenant admin account, enable creating profiles in the tenant.
Migrate to service principal profiles
Migrating to service principal profiles involves the following steps:

1. Create profiles, one profile per customer.

2. Organize your workspaces.
3. Change the application code to use profiles.
4. Test your application with the profiles model.
5. Clean up redundant permissions.

Create Profiles (Required)

Use Profiles REST API with the service principal you created to create one profile for
each customer.

It's a good idea to save a mapping of each data customer ID with its corresponding
profile ID in your database. You'll need this mapping later to make API calls with the
tenant profile.

Organize your workspaces

The easiest way to manage your data is by maintaining one workspace per customer. If
your app already uses this model, you don't need to create new workspaces. However,
you still have to provide each profile with Admin access to the corresponding workspace
using the Add Group User API.

If you don't have one workspace per customer, use the corresponding profile to call
Create Group User API to create a new workspace for each customer.

Organize items in workspaces

You should now have a profile and a workspace for each customer. If you created new
workspaces in the previous step, you need to import items (like reports and semantic
models) into these workspaces. The semantic models you import depend on your
current solution:

If your app uses a separate semantic model for each customer, the semantic model
design can work as it is.

If your app uses one semantic model with row level security (RLS) to provide
different data to different customers, you can get better scalability by creating a
separate semantic model for each customer and using profiles as described in this
article.

After overcoming scalability limitations by using profiles and separate data

sources, you can get even more data separation by using RLS with profiles.
If you rely on Dynamic RLS, the name of the profile will be returned in the DAX
function UserName() .
If you use static RLS and override roles when generating the embed token, you
can continue doing this.

Once the items are ready, import them into the relevant workspaces. To automate the
process, consider using the Import API.

Change the application codes to use profiles

Once you have profiles with Admin access to the relevant workspaces, and a database
with mapping that shows you which profile represents which customer, you can make
the necessary code changes. We recommend that you keep two code flows side by side
and gradually expose the profiles code flow to your customers.

Make the following code changes:

Authorization code change

 If you're using a master user in the Microsoft Entra ID app, change the acquire
token code. Read embed with service principal to learn about creating an app-
only Microsoft Entra token.
If you're using a service principal and you created a new one for profiles, adjust
the code to use the correct service principal ID and secrets.

Management code change

Some apps have management code that automates onboarding a new customer
upon registration. Often, the management code uses Power BI REST APIs to create
workspaces and import content. Most of this code should remain the same, but
you may need to adapt the following details:
Each time you create a new customer tenant, create a new service profile to be
the creator and administrator of the workspace for that tenant.
If you decide to reorganize your Power BI content, edit the code to reflect the
changes.

Embed token code change

Replace the API caller. Make sure a profile calls the GenerateToken API because in
the profiles model, only the specific profile has access to the customer's content.

Validate
It's best practice to test your app thoroughly before moving it to the profiles model.
Reports may load even if there are bugs in the SaaS application code because you didn't
delete the older permissions on the workspaces.

Clean up after migration

Now that you finished the migration and validated the results, remove what you don't
need anymore.

Clean up code: You might want to disable old code paths to ensure that you're
only running new code that relies on profiles.
Clean up workspaces and permissions in Power BI: If you created new workspaces,
you can delete the old workspaces that are no longer in use. If you reused the
same workspaces, you may want to delete the older permissions (such as master
user permissions) on the workspace.

Related content
 Manage service principal profiles

More questions? Try asking the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Security features in Power BI Embedded
Article • 05/14/2024

Power BI Embedded has several ways to filter data and restrict data access to specific
users. Some of these security methods are:

Row-Level Security (RLS) RLS enables you to control access to rows in a database
table through group memberships. When you embed items, you can use RLS to
restrict user access to specific rows of data. With RLS, different users can work with
the same items but see different data.

Object-level security (OLS) OLS enables you to hide specific tables or columns
from report viewers. You can also secure sensitive object names and metadata to
prevent them from being discovered.

Workspace based isolation and multitenancy

In this scenario, each customer has their own separate semantic model. Since each
customer only has access to their own workspace, no further filtering needed,
though this method can be combined with RLS to further filter data within each
organization.

Security solutions for different ISV scenarios

Depending on the situation, some common cases where security measures can be
applied include:

Small to medium sized ISVs who serve multiple customers and want each customer
to see their own data only. If the customer base isn't too large, the ISV can use a
single semantic model and report for all their customers, and use dynamic RLS to
filter the data for each customer.

ISVs who serve one or more large customers or organizations with multiple
departments. The ISV can separate their customers with a combination of static
and dynamic RLS, and possibly OLS.

Large scale ISVs with thousands of customers where each customer needs to see
only their own data. The ISV can use workspace based isolation with service
principal profiles. Each customer can get their own report and semantic model and
the ISV can further filter within each organization using RLS.

Embed a report that uses security features

Depending on your setup, you may have to take several steps before you can generate
an embed token. For instructions on how to embed reports or other items, go to the link
that best describes your specific scenario:

Standard RLS
Embedding paginated reports
SQL Server Analysis Services
Azure Analysis Services
Object-level security

Considerations and limitations

Assigning users to roles within the Power BI service doesn't affect RLS or OLS when
using an embed token (App owns data scenario only).
Although RLS settings don't apply to admins, members, or contributors, when you
supply an identity with an embed token, the RLS permissions of that identity will
be applied to the data.

Related content
Generate an embed token
Row-Level security (RLS) with Power BI

More questions? Try asking the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Embed a report with RLS
Article • 06/03/2024

APPLIES TO: App owns data User owns data

This article explains how to embed Power BI content that uses RLS into a standard Power
BI app owns data application.

Prerequisites
For a detailed explanation on how to set up RLS, refer to Row-level security (RLS) with
Power BI.

When you define your RLS roles, keep in mind that the DAX expression you use
determines if the RLS model is static or dynamic.

When to use static and dynamic security

Static security uses a fixed value in the DAX filter to define each role. It's simple to
implement but difficult to maintain when there are many users or organizations
involved.

Static security works best for an ISV that serves one or a few big customers where each
department needs to access different data.

Dynamic security uses a DAX function ( username() or userprincipalname() ) to define

the roles. Dynamic security provides more flexibility and allows you to manage your data
using fewer roles and less maintenance.

Static security
With static roles, you pass the role to Power BI when you generate an embed token, and
the user sees data according to that role. To create static security roles, enter a fixed
value in the DAX filter.

For example, you can define the role of Eastern US as [Region] = "East"
Let's say [email protected] is a user of your app. You want to give John access to data
from the Eastern US role. To embed a report for [email protected], generate an embed
token using the Eastern US role. The resulting data is filtered for [Region] = "East" .

７ Note

When you generate the embed token, you need to supply a username, but the
username can be any string. Static roles have a fixed value that isn't dependent on
a username, so once the ISV determines the user's role and passes it to the embed
token, the data is filtered according to that role regardless of what username was
passed.

Dynamic security
Dynamic security uses the DAX function ( username() or userprincipalname() ) to define
the role.

In the user owns data scenario, the RLS model automatically filters data based on the
roles of the specific user. With app owns data, Power BI doesn't know the usernames of
the ISV's customers, so you can use the username() function to dynamically filter the
data.

Create a role in Power BI Desktop using the username() function. For example, you can
create a role called CountryDynamic and define it as [CountryRegionCode] = username()
Let's say you want to give your user, [email protected], access to data for France.
When you generate an embed token for [email protected], you pass the string France
as the username in the CountryDynamic role. Your data is filtered according to
[CountryRegionCode] = France.

JSON

{
"accessLevel": "View",
"identities": [
{
"username": "France",
"roles": [ "CountryDynamic"],
"datasets": [ "fe0a1aeb-f6a4-4b27-a2d3-b5df3bb28bdc" ]
}
]
}

When using dynamic security in this scenario, you only need one role for all regions. The
region name is used as the effective identity.

Generate an embed token

When you're ready to embed the report into your app, you need to generate an embed
token. To generate a token using the Embed Token API, pass the following information
to the API.
 username (required) – If the roles are dynamic, the username string is used as the
filter. For static roles, the username doesn't affect the RLS and can be any string at
all. Only a single username can be listed.
roles (required) – The role(s) used when applying Row Level Security rules. If
passing more than one role, they should be passed as a string array.
dataset (required) – The dataset that is applicable for the item you're embedding.

You can now embed the report into your app. The report filters data according to the
RLS applied.

C#

public EmbedToken GetEmbedToken(Guid reportId, IList<Guid> datasetIds,

[Optional] Guid targetWorkspaceId)
{
PowerBIClient pbiClient = this.GetPowerBIClient();

// Defines the user identity and roles.

var rlsIdentity = new EffectiveIdentity(
username: "France",
roles: new List<string>{ "CountryDynamic" },
datasets: datasetIds.Select(id => id.ToString()).ToList());
);

// Create a request for getting an embed token for the rls identity
defined above
var tokenRequest = new GenerateTokenRequestV2(
reports: new List<GenerateTokenRequestV2Report>() { new
GenerateTokenRequestV2Report(reportId) },
datasets: datasetIds.Select(datasetId => new
GenerateTokenRequestV2Dataset(datasetId.ToString())).ToList(),
targetWorkspaces: targetWorkspaceId != Guid.Empty ? new
List<GenerateTokenRequestV2TargetWorkspace>() { new
GenerateTokenRequestV2TargetWorkspace(targetWorkspaceId) } : null,
identities: new List<EffectiveIdentity> { rlsIdentity }
);

// Generate an embed token

var embedToken = pbiClient.EmbedToken.GenerateToken(tokenRequest);

return embedToken;
}

Considerations and limitations

Depending on your setup, you may have to take several steps before you can
generate an embed token. For information about the different scenarios, see
Embed a report that uses security features.
 The user that generates the embed token has to be a member or admin in both
workspaces (the dataset workspace and the report workspace).
When generating the embed token, you need to provide a username and a role. If
you don't, one of the following events will occur, depending on if the token is
being generated by service principal or master user:
For a service principal, token generation fails.
For a master user, token generation succeeds but the data isn't filtered (all the
data is returned).

Related content
RLS guidance
Generate an embed token

More Questions? Try the Power BI Community.

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Implementing row-level security in
embedded paginated reports
Article • 06/04/2024

APPLIES TO: App owns data User owns data

This article explains how to embed a paginated report that uses RLS (row-level security)
into your app owns data application.

７ Note

This article is only relevant for app owns data customers.

To use RLS for your paginated reports:

1. Set up the environment to filter the report

2. Filter the data at report or query level
3. Pass the configured parameter using an embed token

Prerequisites
This article assumes that you know how to embed a Power BI paginated report. It
explains how to generate the embed token so that the report only shows what the
user has permission to access.

Paginated reports are created using the SQL Server Reporting Services engine, and
not the Power BI (Analysis Services) engine, so the RLS filtering is set up in Power
BI Report Builder.

Set up the environment

To apply row-level security to a Power BI paginated report, use the built-in field UserID
to assign a parameter. This parameter is used to filter or query your data.

Then, pass the UserID to the Embed Token - Generate Token API to get the embed
token.

Use UserID as a filter at report or query level

You can use UserId as a filter or in a query to the data source.

Filter the data

1. In the Semantic model Properties window, from the left pane, select Filter.

2. From the Expression dropdown menu, select the parameter you want to use for
filtering the data.
3. Select the Value function button.

4. In the Expression window, from the Category list, select Built-in Fields.
5. From the Item list, select UserID and select OK.
6. In the Semantic model Properties window, verify that the expression is your
selected parameter = UserID, and select OK.
Using a query
1. In the Semantic model Properties window, from the left navigation pane, select
Parameters, and select Add.

2. In the Parameter Name field enter @UserID, and in the Parameter Value add
[&UserID].
 3. From the left pane, select Query, in the Query add the UserID parameter as part of
your query, and select OK.

７ Note

In the screenshot below the color parameter is used as an example (WHERE

FinalTable.Color = @UserID). If needed, you can create a more complex query.

Generate an embed token

When you embed a paginated report for your customers, use the Reports
GenerateTokenInGroup API to get the embed token. This token can also be used to filter
some data out of the paginated report.

You can only generate a token using a service principal. You can't generate a token as a
master user. The service principal has to have at least member permissions to the
workspace in the Power BI service. (If the service principal is a contributor or viewer it
isn't able to generate a token).

To generate a token, assign the username field with the information you want to display.
For example, in a paginated report that has a color parameter, if you enter green in the
username field, the embed token restricts the embedded data to just the data that has

green as its value in the color column.

JSON

{
"reports": [
{
"id": "8d57615e-cfed-4d60-bd21-7dc05727193c"
}
],
"identities": [
{
"username": "green",
"reports": [
"8d57615e-cfed-4d60-bd21-7dc05727193c"
]
}
]
}

７ Note

If you generate embed token without specifying a user-id, the object-id of service
principal will be used.

Considerations and limitations

Master-user isn't supported with paginated reports for embed for your customers.
Master-user is supported for embed for your organization.
The service principal must have workspace permissions of at least member or (not
viewer or contributor).
Related content
Generate an embed token

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Embed a report on an on-premises SQL
Server Analysis Services (SSAS)
Article • 01/23/2024

APPLIES TO: App owns data User owns data

This article explains how to embed Power BI content with an on-premises Analysis
Services Tabular Model live connection into a standard Power BI app owns data
application. This article applies to all live connection SSAS models whether or not they
implement RLS.

In this scenario, the database is on the SSAS (on-premises) model, and the Power BI
engine connects to it via a gateway. The security roles (RLS) and permissions, if there are
any, are defined in the SSAS model, and not in Power BI Desktop.

Who this article is for

This article is mostly relevant for ISVs who already have an on-premises (SSAS) database
setup (with or without RLS) and want to embed content directly from there.

ISV setup
On-premises row level security is only available with a live connection, but you can
create a live connection to any database whether or not it implements RLS. This
includes:

Databases with no RLS roles set up

Databases with members who belong to one or more roles
Databases with static or dynamic security roles

To embed a report from an SSAS model, you need to do the following actions:

1. Set up the gateway

2. Create a live connection
3. Generate an embed token

Set up the gateway

Add a data source connection to the SSAS gateway
Enter the Datasource name, datasource type, Server, database, a username and
password that the active directory recognizes.

For more information on creating and managing a gateway see Add or remove a
gateway data source.

Give service principal or master user permissions on the

gateway
The user generating the embed token also needs one of the following permissions:

Gateway admin permissions

Datasource impersonate permission (ReadOverrideEffectiveIdentity)

Users with impersonate (override) permission have a key icon next to their name.

Follow these instructions to grant gateway permissions to your master user, service
principal, or service principal profile.
 Master user

Do one of the following:

Give the master user gateway admin permissions through the UI -

recommended
Give the master user gateway admin permissions using the API
Give the master user impersonate permissions

Map User names

If the usernames on the on-premises directory and the Microsoft Entra directory are
different and you want to view data in the portal, you need to create a user mapping
table that maps each user or role in Microsoft Entra ID to users from the on-premises
database. For instructions on mapping user names, go to Manual user name remapping

For more information see Map user names for Analysis Services data sources.

Create a live connection

Once the environment is set up, create a live connection between Power BI Desktop and
the SQL server and create your report.

1. Start Power BI Desktop and select Get data > Database.

2. From the data sources list, select the SQL Server Analysis Services Database and
select Connect.
3. Fill in your Analysis Services tabular instance details and select Connect live. Then
select OK.
Generate an embed token
To embed your report in the embed for your customers scenario, generate an embed
token that passes the effective identity to Power BI. All live connections to AS engines
need an effective identity even if there's no RLS implemented.

If there's no RLS set up, only the Admin has access to the database so you want to use
the Admin as the effective identity.

The information needed to generate an embed token depends on if you're connected to

Power BI using a service principal or as a master user, and also if the database has RLS.

Master user embed token

To generate the embed token, provide the following information:

Username (Optional if no RLS. Required for RLS) - A valid username

recognized by the SSAS that will be used as the effective identity. If the
database doesn't use RLS, and no username is provided, the master user's
credentials are used.
Role (required for RLS) - The report will only display data if the effective
identity is a member of the role.

Example:

C#

public EmbedToken GetEmbedToken(Guid reportId, IList<Guid> datasetIds,

[Optional] Guid targetWorkspaceId)
{
PowerBIClient pbiClient = this.GetPowerBIClient();

// Define the user identity and roles. Use one of the following:

var rlsidentity = new EffectiveIdentity( //If no RLS

username: "Domain\\Username", // can also be [email protected]
datasets: new List<string>{ datasetId.ToString()}
)

var rlsidentity = new EffectiveIdentity( // If RLS

username: "[email protected]",
roles: new List<string>{ "MyRole" },
datasets: new List<string>{ datasetId.ToString()}
)

// Create a request for getting an embed token for the rls identity
defined above
var tokenRequest = new GenerateTokenRequestV2(
 reports: new List<GenerateTokenRequestV2Report>() { new
GenerateTokenRequestV2Report(reportId) },
datasets: datasetIds.Select(datasetId => new
GenerateTokenRequestV2Dataset(datasetId.ToString())).ToList(),
targetWorkspaces: targetWorkspaceId != Guid.Empty ? new
List<GenerateTokenRequestV2TargetWorkspace>() { new
GenerateTokenRequestV2TargetWorkspace(targetWorkspaceId) } : null,
identities: new List<EffectiveIdentity> { rlsIdentity }
);

// Generate an embed token

var embedToken = pbiClient.EmbedToken.GenerateToken(tokenRequest);

return embedToken;
}

Now you can embed your report in your app, and your report will filter data according
to the permissions of the user accessing the report.

Considerations and limitations

CustomData isn't supported.

Related content
Generate an embed token

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Embed a report with an Azure Analysis
Services (AAS) database
Article • 11/08/2023

APPLIES TO: App owns data User owns data

This article explains how to embed a Power BI report that uses data stored in Azure
Analysis Services (AAS), in an embed for your customers scenario. This article is aimed at
independent software developers (ISVs), who want to embed a report with AAS data
whether or not the database implements row-level security (RLS).

Prerequisites
You'll need a report with a live connection to AAS database, with or without RLS.

Dynamic security - RLS

If you want your report to implement dynamic RLS, use the customeData function. Since
you can't override the effective identity, we recommend creating new roles with
customData . You can also use roles that have the username or userPrincipalName

functions, if you replace them with customData .

Follow these steps to create a new role and add the customData function to the role.

1. Create a role in the Analysis Services server.

2. In the General settings, provide a Role Name and set the database permissions to
Read only.
3. In the Membership settings, add the users that are going to call the Embed Token -
Generate Token API. If you're using a service principal that's not an admin, add that
as well.
4. In the Row filters settings, set your DAX query using the CUSTOMDATA() function.
Service principal
If you're using a service principal to embed the report, make sure the service principal is
a server admin or role member of AAS. To grant AAS admin permissions to the service
principal, see Add a service principal to the server administrator role. To add the service
principal as a role member, go to the Membership settings.

Use the service principal object ID as the username (effective identity).

Analysis Service migration

You can migrate from AAS to Power BI Premium even if you have an embedded AAS
report. Your embedded report won't break during the migration, as long as the principal
that's calling the Embed Token - Generate Token API, is a member or admin of the
workspace.

７ Note
 If the service principal is not an admin, and you don't want to make it an admin of
the workspace when you migrate, migrate that model into a separate workspace
where you can give it admin permissions.

Generate an embed token

Use the Generate Token API to generate an embed token that overrides the effective
identity.

The information needed to generate an embed token depends on how you're

connected to Power BI (service principal or master user), and also if the database has
RLS.

Master user embed token

To generate an embed token, provide the following information:

Username (Optional if no RLS. Required for RLS) - The username must be the
same as API caller (in this case, the Master user's UPN). If the database doesn't
use RLS, and no username is provided, the master user's credentials are used.
Role (required for RLS) - The report will only display data if the effective
identity is a member of the role.

Example:

Define the user identity and roles for one of the following three scenarios:

If RLS isn't implemented:

There is no need to define any effective identity.

If using static RLS:

C#

var rlsidentity = new EffectiveIdentity( //If static RLS

username: "[email protected]",
roles: new List<string>{ "MyRole" },
datasets: new List<string>{ datasetId.ToString()}
)

If using dynamic RLS:

C#
 var rlsidentity = new EffectiveIdentity( // If dynamic RLS
username: "[email protected]",
roles: new List<string>{ "MyRoleWithCustomData" },
customData: "SalesPersonA"
datasets: new List<string>{ datasetId.ToString()}
)

７ Note

customData in the embed token cannot be larger than 1,024 characters.

Use the effective identity to generate an embed token:

C#

public EmbedToken GetEmbedToken(Guid reportId, IList<Guid> datasetIds,

[Optional] Guid targetWorkspaceId)
{
PowerBIClient pbiClient = this.GetPowerBIClient();
// Create a request for getting an embed token for the rls identity
defined above
var tokenRequest = new GenerateTokenRequestV2(
reports: new List<GenerateTokenRequestV2Report>() { new
GenerateTokenRequestV2Report(reportId) },
datasets: datasetIds.Select(datasetId => new
GenerateTokenRequestV2Dataset(datasetId.ToString())).ToList(),
targetWorkspaces: targetWorkspaceId != Guid.Empty ? new
List<GenerateTokenRequestV2TargetWorkspace>() { new
GenerateTokenRequestV2TargetWorkspace(targetWorkspaceId) } : null,
identities: new List<EffectiveIdentity> { rlsIdentity } // Only
in cases of RLS
);
// Generate an embed token
var embedToken = pbiClient.EmbedToken.GenerateToken(tokenRequest);
return embedToken;
}

Use the embed token to embed the report into your app or website. Your report will
filter data according to the applied RLS in the report.

Next steps
Row-level security with Power BI Embedded
Embed a report with cloud-based RLS
paginated-reports-row-level-security
Embed a report with token-based
identity (SSO)
Article • 12/21/2023

APPLIES TO: App owns data User owns data

The token-based identity allows an ISV to use an Microsoft Entra access token to pass
the identity of a customer to an Azure SQL database managed in the customer's tenant.

ISV customers that keep and manage their data in Azure SQL Database can keep their
data secure in their tenant when integrating with Power BI Embedded in the ISV app.

When generating the embed token, specify the identity of the user in Azure SQL by
passing that user's Microsoft Entra access token for the Azure SQL server. The access
token is then used to pull only the relevant data for that user from Azure SQL, for that
specific session.

Set up token-based identity

The token-based identity only works for DirectQuery models on a capacity connected to
an Azure SQL Database that's configured to allow Microsoft Entra authentication. The
semantic model's data source must be configured to use end users' OAuth2 credentials,
to use a token-based identity. Learn more about Microsoft Entra authentication for
Azure SQL Database.

Set up in portal

1. From the Power BI portal, select Semantic model > More Options (three
dots) > Settings > Data source credentials > Edit credentials.

2. Check the OAuth2 option box.

Generate an identity token
To create an access token for Azure SQL, the app must have Access Azure SQL DB and
Data Warehouse delegated permission to Azure SQL Database API on the Microsoft
Entra app registration configuration in the Azure portal.
Authenticate and acquire a token for the user from the Azure AD v2 endpoint for the
following scope: https://database.windows.net/.default

See the following MSAL code samples for help:

Code samples for Microsoft identity platform authentication and authorization -

Microsoft Entra | Microsoft Learn
Microsoft identity platform and OAuth 2.0 authorization code flow

Generate embed token

To Embed a report with token-based identity, generate an embed token that contains
the token base identity of the desired ISV user. See the following examples for
generating embed tokens for different scenarios.

Power BI report with SSO

JSON

{
"datasets": [
{
"id": "66ba5010-xxxx-xxxx-xxxx-f2bf0125abeb",
}
],
"reports": [
{
"allowEdit": false,
"id": "9e6da541-xxxx-xxxx-xxxx-7d9442827cce"
}
],
"datasourceIdentities": [
{
 "identityBlob": "eyJ…",
"datasources": [
{
"datasourceType": "Sql",
"connectionDetails": {
"server": "YourServerName.database.windows.net",
"database": "YourDataBaseName"
}
}
]
}
]
}

The following example shows an embedded Power BI report with SSO and RLS applied
to the dataset:
Object-level security
Article • 06/03/2024

APPLIES TO: App owns data User owns data

This article explains how to embed Power BI content that uses OLS in a Power BI App
owns data (embed for your customers) scenario.

In this scenario, the ISV has a table with sensitive data and metadata that they want to
hide from the report customers.

For more information on OLS, go to Object-level security (OLS).

Prerequisites
This article assumes that you have a report that uses OLS and that you want to embed it
into an app. To create a report that uses OLS, see Object-level security (OLS).

The report can be built using any of the following models:

Cloud OLS
Live connected report to Azure Analysis Services with OLS roles
Live connected report to SQL Server Analysis Services with OLS roles

Embed a report that uses object-level security

The process of generating embed tokens for items that use OLS is the same as for static
RLS. You need the role and user name.

If the report you want to embed is using one of the following scenarios, you might need
to take some extra steps:

Cloud OLS token generation

SQL Server Analysis Services (SSAS) token generation
Microsoft Entra ID token generation

The following example shows how to generate a token to hide a table with sensitive
information using OLS:

C#

public EmbedToken GetEmbedToken(Guid reportId, IList<Guid> datasetIds,

[Optional] Guid targetWorkspaceId)
 {
PowerBIClient pbiClient = this.GetPowerBIClient();

// Defines the user identity and roles.

var olsIdentity = new EffectiveIdentity(
username: "All",
roles: new List<string>{ "SensitiveTableOLS" }, // Role created
to hide a table that has sensitive information
datasets: new List<string>{ datasetId.ToString()}
);

// Create a request for getting an embed token for the OLS identity
defined above
var tokenRequest = new GenerateTokenRequestV2(
reports: new List<GenerateTokenRequestV2Report>() { new
GenerateTokenRequestV2Report(reportId) },
datasets: datasetIds.Select(datasetId => new
GenerateTokenRequestV2Dataset(datasetId.ToString())).ToList(),
targetWorkspaces: targetWorkspaceId != Guid.Empty ? new
List<GenerateTokenRequestV2TargetWorkspace>() { new
GenerateTokenRequestV2TargetWorkspace(targetWorkspaceId) } : null,
identities: new List<EffectiveIdentity> { olsIdentity }
);

// Generate an embed token

var embedToken = pbiClient.EmbedToken.GenerateToken(tokenRequest);

return embedToken;
}

Considerations and limitations

See restrictions for OLS models.

Related content
Object-level security in Azure Analysis Services

More questions? Try asking the Power BI Community .

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Embedded analytics solution accelerators from
Microsoft partners
Article • 05/09/2024

Microsoft's partners offer accelerators to expedite the integration of embedded analytics solutions with your applications.
These accelerators are designed to be cost-effective and efficient, reducing the time-to-market for your Power BI embedded
analytics solutions, particularly for multitenant, customer-facing applications. They're particularly useful for quickly
advancing proof-of-concept (PoC) or pilot projects. Accelerators simplify the implementation process and assist in
managing Power BI capacity and billing.

Key advantages of using accelerators include:

Enhanced Personalization and Functionality: Accelerators enhance user experience, offering personalized features for
Embed for your customers scenario. This includes flexible options for end-user authentication, authorization,
multitenancy, and permissions management.

Simplified Implementation: The complex details of implementing Power BI embedded solutions are abstracted away.
Some accelerators offer backend functionality through an SDK, with the need for additional client front-end code
development.

Customization and White-Labeling: Once installed, you can white-label the solution, tailor its capabilities, and
customize the user interface. White-label the solution, configure its capabilities, and customize the user experience
once installed.​

Acquisition and Ownership: Accelerators are developed and owned by Microsoft's partners and need to be purchased
directly from them. They're cloud-based solutions deployed in your Azure environment, utilizing Azure and Fabric with
Power BI services from Microsoft. Existing Microsoft subscriptions or licenses can be reused, the accelerators are also
available for deployment through the Azure Marketplace.

Integration Flexibility: Accelerators can function as standalone applications or be fully integrated with your existing
application, as outlined in the Deployment and integration options table.

Watch a video that provides an overview of embedded solution accelerator partner programs .

Different partner accelerators vary in their deployment, acquisition/billing methods, and capabilities. The following table
briefly describes each of the current partners’ embedded analytics solution accelerators:"

There are several partner accelerators that vary in their deployment, acquisition/billing options and their capabilities. ​

ﾉ Expand table

Partner Description Website/Product link

(accelerator)

Shift Analytics' accelerator:

The Reporting Hub is a web-based business intelligence platform that seamlessly
integrates with Power BI using Embedded technology. It's a plug 'n' play white label
application that deploys to your Azure environment and allows you to instantly deliver
Power BI in a more efficient and simplified manner. The Reporting Hub
Watch an overview interview video of the Reporting Hub .

MAQ Software's accelerator:

EmbedFAST is a ready-to-use API that embeds Power BI into your existing apps with
ease. Seamlessly embed Power BI with comprehensive features such as role-based EmbedFAST
access management and no per user licenses—without having to build from scratch.
Save time, effort, costs, and resources by using EmbedFAST.
Watch an overview interview video of EmbedFAST .
 Partner Description Website/Product link
(accelerator)

iLink Digital's accelerator:

EmbeDash enables Independent Software Vendors (ISVs) to provide Analytics as a
Service (AaaS) using Power BI Embedded. This Accelerator reduces the time to market EmbeDash
and allows ISVs to add strong self-service reporting capabilities, without having to code
them themselves.
Watch an overview interview video of EmbeDash .

The following diagram illustrates the main modules of an accelerator and how they relate to your existing multitenant web
application:

Accelerator capabilities
Different accelerators provide different frontend and backend capabilities including the following options:

Frontend capabilities
Navigation menu for categories and items of Power BI​

Action bar above the Power BI iFrame to control the UX and invoke functionality ​
 End user bookmark management & visual personalization​

Export report to file printouts (PDF, PPTX, PNG, and more for Paginated reports)​

UX pane control and report edit/view toggle​

Report subscriptions and scheduling of printouts​

Seamless multitenancy and user permissions support​

Show each tenant user only their own data even when using the same report across the tenant

Show the user only the items and data they have access to

Allow switching to edit mode based on user permissions (access level on report) ​

Multi-language support for web frontend

To see which partner's solution contains which options, see the comparison tables.

Backend capabilities
The following features and capabilities are available in the backend and admin modules of the accelerators:

Backend module​
Support multiple end user authentication providers, potentially a different one per tenant​

Generate and refresh access and embed tokens per tenant workspace isolation and user permissions​

Support frontend features: asynchronous print to file and report subscriptions, scheduling & distribution​

Expose backend SDK for your custom frontend embedded as iFrame in the existing ISV app​

Admin module (including UI and config database)​

Multitenancy solution management within the same Power BI tenant

Auto provision workspace when on-boarding a new tenant​

Isolate tenants’ data and reports in their respective workspaces ​

Isolate tenant PBI access with dedicated service principal profile identity to create/access tenant’s workspace​

Optionally sync & reuse existing information on the app’s tenants and their end users​

Manage tenant's end user access of PBI items and data (with RLS/dynamic binding for dataset) ​

Collect and visualize usage analytics of tenants and their users​

Capacity management​

Assign workspace to capacity to support global multi-geo deployment and to scale out with multiple capacities​

Manage capacities operation pause resume and scale up/scale down​

Publishing & management of tenant’s PBI content​

Tenant use monetization and streamlined licensing billing & payment processing

To see which partner's solution contains which options, see the comparison tables in the next section.
Comparison of accelerators from our partners
The following tables compare features of the different accelerators from our partners. The tables are divided into the
following sections:

Deployment options
Acquisition and billing options
Added capabilities

Deployment and integration options

ﾉ Expand table

Partner Stand alone URL redirect Embedded in App’s iFrame Backend + SDK only
(accelerator)

Shift Analytics​ ✔​ ✔​ ✔​ ​
The Reporting Hub

MAQ Software​ ​ ​ ✔​
EmbedFAST

iLink Digital​ ✔​ ​ ​ ​
EmbeDash

Acquisition and billing options

ﾉ Expand table

Partner Monthly Monthly Free trial One As part

(accelerator) subscriptions: subscriptions: time purchase ​ of consulting engagement​
Direct billing Azure Marketplace

Shift Analytics​ ✔​ ✔​ ​ ​
The Reporting
Hub ​

MAQ Software​ ​ ✔​ ✔​
EmbedFAST

iLink​ ​ ✔​ ​ ✔​
EmbeDash

Added capabilities
ﾉ Expand table

Partner Personal​ Report​ Control​ Navigation​ Multi- Tenant Power BI Report Tenant Multi-
bookmarks Printout UX options Menu tenancy​ specific​ item​ subs.​ billing​ language​
authN publishing scheduling & portal
&​ &​ payment​ support​
white- distribution​ processing​
labeling​

Shift ✔ ✔ ✔ ✔ ✔ ✔ ​ ✔​ ✔​ ✔
Analytics​
The
 Partner Personal​ Report​ Control​ Navigation​ Multi- Tenant Power BI Report Tenant Multi-
bookmarks Printout UX options Menu tenancy​ specific​ item​ subs.​ billing​ language​
authN publishing scheduling & portal
&​ &​ payment​ support​
white- distribution​ processing​
labeling​

Reporting
Hub ​

MAQ ✔​ ✔​ ✔ ✔​ ✔​ ​ ✔​ ✔​ ​
Software​
EmbedFAST ​

iLink Digital​ ✔​ ✔​ ✔ ✔​ ✔ ​ ✔ ​ ​
EmbeDash

Related content
To watch interview video recordings describing the accelerator program and each accelerator visit the Microsoft
Partner Showcase - Embedded Analytics Solution Accelerators page .

To learn more about each partner’s solution accelerator, visit their corresponding product website:

The Reporting Hub

EmbedFAST

EmbeDash

Find a Microsoft partner for consulting and assistance in building Power BI content.

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Troubleshoot your embedded
application
Article • 01/24/2024

This article discusses some common issues that can come up when embedding content
from Power BI.

Troubleshooting tools

Fiddler Trace
Fiddler is a free tool from Telerik that monitors HTTP traffic. You can see the traffic
with the Power BI APIs from the client machine. This tool might show errors and other
related information.

F12 in Browser for frontend debugging

The F12 key launches the developer window within your browser. This tool lets you look
at network traffic and see other valuable information.
Extract error details from Power BI response
This code snippet shows how to extract the error details from an HTTP exception:

C#

public static string GetExceptionText(this HttpOperationException exc)

{
var errorText = string.Format("Request: {0}\r\nStatus: {1}
({2})\r\nResponse: {3}",
exc.Request.Content, exc.Response.StatusCode,
(int)exc.Response.StatusCode, exc.Response.Content);
if (exc.Response.Headers.ContainsKey("RequestId"))
{
var requestId = exc.Response.Headers["RequestId"].FirstOrDefault();
errorText += string.Format("\r\nRequestId: {0}", requestId);
}

return errorText;
}

We recommend logging the Request ID (and error details for troubleshooting). Provide
the Request ID when approaching Microsoft support.

App registration

App registration failure

Error messages within the Azure portal or the Power BI app registration page will notify
you if you don't have sufficient privileges to register your app. To register an application,
you must be an admin in the Microsoft Entra tenant, or application registrations must be
enabled for non-admin users.

Power BI service doesn't appear in the Azure portal when

registering a new app
At least one user must be signed up for Power BI. If you don't see Power BI service
listed within the API list, no user is signed up for Power BI.

What's the difference between an application object ID

and a principal object ID?
When you register a Microsoft Entra app, there are two parameters called object ID. This
section explains the purpose of each parameter, and how to obtain it.

Application object ID

The application object ID, also known simply as the object ID, is the unique ID of your
Microsoft Entra application object.

To get the application object ID, navigate to your Microsoft Entra app, and copy it from
the Overview.

Principal object ID

The principal object ID, also known simply as the object ID, is the unique ID of the
service principal object associated with your Microsoft Entra application.

To get your principal object ID, navigate to your Microsoft Entra app, and from the
Overview, select the app link in Managed application in local directory.

From the Properties section, copy the Object ID.

Authentication

Authentication failed with AADSTS70002 or

AADSTS50053
(AADSTS70002: Error validating credentials. AADSTS50053: You've tried to sign in too
many times with an incorrect User ID or password)

If you're using Power BI Embedded and Microsoft Entra direct authentication, you might
receive a message like the previous message when you try to sign in, because direct
authentication isn't enabled.

You can turn direct authentication back on using an Microsoft Entra policy that is scoped
to the organization, or a service principal.

We recommend you enable this policy only on a per-app basis.

To create this policy, you need to be a Global Administrator for the directory where
you're creating the policy and assigning it. Here's a sample script for creating the policy
and assigning it to the SP for this application:

1. Install the Microsoft Graph PowerShell SDK.

2. Run the following PowerShell commands line-by-line (making sure the variable
$sp doesn't have more than one application as a result).

PowerShell

Connect-MgGraph -Scopes
"Directory.Read.All","Policy.ReadWrite.ApplicationConfiguration"

$sp = Get-MgServicePrincipal -Filter "DisplayName eq

 'Name_Of_Application'"

$policy = New-MgBetaPolicyActivityBasedTimeoutPolicy -Definition @("

{`"AllowCloudPasswordValidation`":true}") `
-DisplayName EnableDirectAuth -IsOrganizationDefault:$false

$params = @{
"@odata.id" =
"https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/$polic
y.Id"
}
New-MgBetaServicePrincipalClaimMappingPolicyByRef -ServicePrincipalId
$sp.Id `
-BodyParameter $params

After assigning the policy, wait approximately 15-20 seconds for propagation before
testing.

Generate token fails when providing effective identity

GenerateToken can fail with effective identity supplied for a few different reasons:

The semantic model doesn't support effective identity.

Username wasn't provided.
Role wasn't provided.
DatasetId wasn't provided.

The user doesn't have the correct permissions.

To determine the problem, try the following steps:

Run get dataset. Is the property IsEffectiveIdentityRequired true?

Username is required for any EffectiveIdentity .
If IsEffectiveIdentityRolesRequired is true, Role is required.
DatasetId is required for any EffectiveIdentity .

For Analysis Services, the master user has to be a gateway admin.

AADSTS90094: The grant requires admin permission

Symptoms:

When a non-admin user tries to sign in to an application for the first time while granting
consent, then gets one of the following errors:

Output
 ConsentTest needs permission to access resources in your organization
that only an admin can grant. Ask an admin to grant permission to this
app before you can use it.

Output

AADSTS90094: The grant requires admin permission.

An admin user can sign in and grant consent successfully.

Root cause:

User consent is disabled for the tenant.

Several fixes are possible:

Enable user consent for the entire tenant (all users, all applications):

1. In the Azure portal, navigate to Microsoft Entra ID > Users and groups > User
settings.
2. Enable the Users can consent to apps accessing company data on their behalf
setting and save the changes.
 An admin can grant permissions to the application - either for the entire tenant or
a specific user.

CS1061 error
Download Microsoft.IdentityModel.Clients.ActiveDirectory if you experience the
following error:

Output

'AuthenticationContext' does not contain a definition for 'AcquireToken' and

no accessible 'AcquireToken' accepting a first argument of type
'AuthenticationContext' could be found (are you missing a using directive or
an assembly reference?)

Microsoft Entra token for a different tenant (guest user)

When you embed for your organization, to allow Microsoft Entra guest users access to
your content, you need to specify the tenant ID in the authorityUri parameter.

URL for authenticating in your organization's tenant:

https://login.microsoftonline.com/common/v2.0

URL for authenticating a guest Microsoft Entra user:

https://login.microsoftonline.com/<tenant ID>

To find your tenant ID, you can use the instructions in Find the Microsoft Entra tenant ID
and primary domain name.

For more information, see Making your application multi-tenant.

Data sources
ISV wants to have different credentials for the same data
source
A data source can have a single set of credentials for one master user. If you need to use
different credentials, create more master users. Then, assign the different credentials to
each of the master users' contexts, and embed using the Microsoft Entra token of that
user.

Troubleshoot your embedded application with

the IError object
Use the IError object returned by the error event from the JavaScript SDK to debug your
application and better understand the cause of your errors.

After acquiring the IError object, you should look at the appropriate common errors
table that fits the embed type you're using. Compare the IError properties with the ones
in the table and find the possible reason(s) for the failure.

Typical errors when embedding for Power BI users

ﾉ Expand table

Message Detailed Error Possible

Message Code reason(s)

TokenExpired Access token 403 Expired token

has expired,
resubmit with
a new access
token

PowerBIEntityNotFound Get report 404 Wrong

failed Report ID
Report
doesn't exist

Invalid parameters powerbiToken N/A No access

parameter not token
specified provided
No Report
ID provided

LoadReportFailed Fail to 403 Bad

initialize - access token
Message Detailed Error Possible
Message Code reason(s)

Couldn't Embed
resolve cluster type doesn't
match token
type

PowerBINotAuthorizedException Get report 401 Wrong

failed group ID

Unauthorized
group

TokenExpired Access token N/A Query

has expired, data
resubmit with Expired
a new access token
token.
Couldn't
render a
report visual
titled: visual
title

OpenConnectionError Can't display N/A Capacity

the visual. paused or
Couldn't deleted while
render a a report
report visual related to the
titled: visual capacity was
title open in a
session

ExplorationContainer_FailedToLoadModel_DefaultDetails Couldn't load N/A Capacity

the model paused
schema Capacity
associated deleted
with this
report. Make
sure you have
a connection
to the server
and try again.

Typical errors when embedding for non-Power BI users

(using an Embed Token)
 ﾉ Expand table

Message Detailed Error Reason(s)

Message Code

TokenExpired Access token 403 Expired token

has expired,
resubmit with
a new access
token

LoadReportFailed Get report 404 Wrong Report ID

failed Report doesn't
exist

LoadReportFailed Get report 403 Report ID doesn't

failed match token

LoadReportFailed Get report 500 Report provided ID

failed isn't a GUID

Invalid parameters powerbiToken N/A No access token

parameter provided
not specified No Report ID
provided

LoadReportFailed Fail to 403 Wrong token type or

initialize - bad token
Couldn't
resolve
cluster

PowerBINotAuthorizedException Get report 401 Wrong/unauthorized

failed group ID

TokenExpired Access token N/A Query data

has expired, Expired token
resubmit with
a new access
token.
Couldn't
render a
report visual
titled: visual
title

OpenConnectionError Can't display N/A Capacity paused or

the visual. deleted while a
Couldn't report related to the
render a capacity was open in
report visual a session
 Message Detailed Error Reason(s)
Message Code

titled: visual
title

ExplorationContainer_FailedToLoadModel_DefaultDetails Couldn't load N/A Capacity paused

the model Capacity deleted
schema
associated
with this
report. Make
sure you have
a connection
to the server
and try again.

Get report fails - error 401 - resolve themselves

In the user owns data scenario, sometimes users will get a 401 error that resolves itself
after they access the Power BI portal. When the 401 error happens, add the RefreshUser
Permissions call in the app as explained in Update user permissions.

Semantic models

Manage which portion of the data your users can see

Any user with read permissions for a semantic model can see the entire schema (tables,
columns and measures) and all the data. You can't control viewing permissions to raw
and aggregated data separately in the same semantic model.

To manage which portion of the data your users can view, use one of the following
methods:

Row-level filtering using Power BI row-level security (RLS).

Object-level security (OLS).

Separate the data into different semantic models. For example, you can create a
semantic model that only contains aggregated data and give your users access to
only that semantic model.

Content rendering
To resolve rendering issues in embedded Power BI items (such as reports and
dashboards), review this section.

Verify that the Power BI item loads in Power BI service

To rule out issues with your application or the embedding APIs, verify that the item can
be viewed in the Power BI service (powerbi.com).

Verify that the Power BI item loads in the Power BI

embedded analytics playground
To rule out issues with your application, verify that the Power BI item can be viewed in
the Power BI embedded analytics playground .

Verify that your access token didn't expire

For security purposes, access tokens (a Microsoft Entra token or an embed token) have a
limited lifetime. You should constantly monitor your access token and refresh it if
needed. For more information, see Refresh the access token.

Performance
To get the best performing embedded content, we recommend that you follow the
Power BI embedded analytics best practices.

Embed setup tool

You can go through the Embedding setup tool to quickly download a sample
application. Then you can compare your application to the sample.

Prerequisites
Verify that you have all the proper prerequisites before using the Embedding setup tool.
You need a Power BI Pro account and a Microsoft Azure subscription.

If you're not signed up for Power BI Pro, sign up for a free trial before you begin.
If you don't have an Azure subscription, create a free account before you begin.
You need to have your own Microsoft Entra tenant setup.
You need Visual Studio installed (version 2013 or later).
Common Issues
Some common issues you might encounter while testing with the Embed setup tool are:

Using the Embed for your customers sample application

If you're working with the Embed for your customers experience, save and unzip the
PowerBI-Developer-Samples.zip file. Then open the PowerBI-Developer-Samples-
master\App Owns Data folder and run the PowerBIEmbedded_AppOwnsData.sln file.

When selecting Grant permissions (the Grant permissions step), you get the
following error:

Output

AADSTS70001: Application with identifier <client ID> wasn't found in the

directory <directory ID>

The solution is to close the popup, wait a few seconds and try again. You might need to
repeat this action a few times. A time interval causes the issue from completing the
application registration process to when it's available to external APIs.

The following error message appears when running the sample app:

Output

Password is empty. Please fill password of Power BI username in web.config.

This error occurs because the only value that isn't being injected into the sample
application is your user password. Open the Web.config file in the solution and fill the
pbiPassword field with your user's password.

If you get the error:

Output

AADSTS50079: The user is required to use multi-factor authentication.

You need to use a Microsoft Entra account that doesn't have MFA enabled.

Using the Embed for your organization sample application

If you're working with the Embed for your organization experience, save and unzip the
PowerBI-Developer-Samples.zip file. Then open the PowerBI-Developer-Samples-
master\User Owns Data\integrate-report-web-app folder and run the pbi-saas-embed-
report.sln file.

When you run the Embed for your organization sample app, you get the following
error:

Output

AADSTS50011: The reply URL specified in the request doesn't match the reply
URLs configured for the application: <client ID>

This error is because the redirect URL specified for the web-server application is
different from the sample's URL. If you want to register the sample application, use
https://localhost:13526/ as the redirect URL.

If you want to edit the registered application, update the Microsoft Entra registered
application, so the application can provide access to the web APIs.

If you want to edit your Power BI user profile or data, learn how to edit your Power BI
data.

If you get the error:

Output

AADSTS50079: The user is required to use multi-factor authentication.

You need to use a Microsoft Entra account that doesn't have MFA enabled.

For more information, please see Power BI Embedded FAQ.

For further assistance, contact support or create a support ticket via the Azure
portal and provide the error messages you encounter.

Related content
Power BI Embedded Frequently Asked Questions

More questions? Ask the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Troubleshoot REST APIs
Article • 12/21/2023

API call returns 401

A Fiddler capture might be required to investigate further. The required permission
scope might be missing for the registered application within Microsoft Entra ID. Verify
the required scope is present within the app registration for Microsoft Entra ID within
the Azure portal.

API call returns 403

A 403 error can occur for any of the following reasons. A Fiddler capture might be
required to investigate further.

The user has exceeded the amount of embed token that can be generated on a
shared capacity. Purchase Azure capacities to generate embed tokens and assign
the workspace to that capacity. See Create Power BI Embedded capacity in the
Azure portal.
The Microsoft Entra authorization token expired.
The authenticated user isn't a member of the group (workspace).
The authenticated user isn't an admin of the group (workspace).
The authenticated user doesn't have permissions. Permissions can be updated
using the refreshUserPermissions API.
The authorization header might not be listed correctly. Make sure there are no
typos.

The backend of the application might need to refresh the authorization token before
calling GenerateToken . For more information, see Refresh the access token.

Console

GET https://wabi-us-north-central-
redirect.analysis.windows.net/metadata/cluster HTTP/1.1
Host: wabi-us-north-central-redirect.analysis.windows.net
...
Authorization: Bearer eyJ0eXAiOi...
...

HTTP/1.1 403 Forbidden

...
 {"error":{"code":"TokenExpired","message":"Access token has expired,
resubmit with a new access token"}}

Fix timeout exceptions when using import and

export APIs
When you send a Power BI REST API request, it might arrive at a cluster that doesn't
contain your tenant's data. In that case, redirecting the request might fail due to a
timeout.

To fix the timeout exception, resend the request with the preferClientRouting URL
query parameter set to true . If your request arrives at the wrong cluster, the Power BI
service returns a 307 Temporary Redirect HTTP response. In such cases, you need to
redirect your request to the new address specified in the response HTTPS Location
header.

The update parameters or update data sources

API fails after a few minutes
The following generic error is sometimes returned in the response header:

HTTP/1.1 500 Internal Server Error

JSON

An error has occurred

When using the Datasets - Update Parameters In Group or the Datasets - Update
Datasources In Group APIs, this error might indicate that you're updating a large dataset
that isn't using the large dataset format. Use the large dataset format to avoid the error.

Related content
Power BI Embedded Frequently Asked Questions

More questions? Ask the Power BI Community

Frequently asked questions about
Power BI Embedded
FAQ

If you have other questions, try asking the Power BI Community .

Still have an issue? Visit the Power BI support page .

General
What is Power BI Embedded?
Microsoft Power BI Embedded (PBIE) allows application developers to embed stunning,
fully interactive reports into their applications without having to build their own data
visualizations and controls from scratch.

Who is the target audience for Power BI

Embedded?
Developers and software companies, also known as independent software vendors
(ISVs), coding applications.

How is Power BI Embedded different from Power

BI the service?
Power BI is a software-as-a-service analytics solution that gives organizations a single
view of their most critical business data.

Microsoft developed Power BI Embedded for ISVs wanting to embed visuals into their
applications to help their customers make analytic decisions. This spares ISVs from
having to build their own analytics' solution themselves. Embedded analytics enables
business users to access business data and execute queries against it to generate
insights within the application.

What is the difference between Power BI

Premium and Power BI Embedded?
Power BI Premium is capacity geared toward enterprises who want a complete BI
solution that provides a single view of its organization, partners, customers, and
suppliers. Power BI Premium helps your organization make decisions. Power BI Premium
is a SaaS product that allows users to consume content through mobile apps, internally
developed apps, or at the Power BI portal.

Power BI Embedded is for ISVs who want to embed visuals into their applications. Power
BI Embedded helps your customers make decisions because Power BI Embedded is for
application developers, customers of that application can consume content stored on
Power BI Embedded capacity, including anyone inside or outside the organization. You
can't share Power BI Embedded capacity content through one-click publish to Web or
one-click publish to SharePoint.

What is the Microsoft recommendation for when

a customer should buy Power BI Premium vs.
Power BI Embedded?
Microsoft recommends that enterprises buy Power BI Premium, an enterprise-grade,
self-service cloud BI solution. We recommend ISVs buy Power BI Embedded for its
cloud-powered embedded analytics components. However, a customer has no
restriction on which product to buy.

There may be some cases where an ISV (typically large), in addition to app embedding,
wants to use a P SKU to get the extra benefits of the pre-packaged Power BI service
within their organization.

For more on the differences between Premium and Embedded, see Which SKU should I
use.

How many embed tokens can I create?

Embed tokens with Pro or Premium Per User (PPU) license are intended for development
testing, so a Power BI master account or service principal can only generate a limited
number of tokens. Purchase a capacity for embedding in a production environment.
There's no limit to how many embed tokens you can generate when you purchase a
capacity. In development testing, you can use free embed trial tokens with a Pro license.
To embed in a production environment, you must purchase a capacity.

Embedded
How can I autoscale an Embedded Premium
capacity?
Embedded Premium capacities don't provide an out-of-the-box vertical autoscale
feature. To learn about alternative autoscale options for Embedded Premium capacities,
see [Autoscaling in Embedded(./azure-pbie-scale-capacity.md#autoscale-your-capacity).

How is an Embedded Premium resource

utilization evaluated?
Power BI Embedded Premium evaluates your level of utilization by aggregating
utilization records every 30 seconds. Each evaluation is composed of two different
aggregations: Interactive utilization and background utilization.

Interactive utilization is evaluated by considering all the interactive operations that

completed on or near the current half-minute evaluation cycle.

Background utilization is evaluated by considering all the background operations that

completed during the past 24 hours, where each background operation contributes only
1/2880 of its total CPU cost (there are 2880 evaluation cycles in each 24-hour period).

A capacity consists of a defined number of v-cores. The Microsoft Fabric Capacity

Metrics app tracks the utilization of your capacity v-cores. The CPU usage reported in
the app drives the need to autoscale.

What happens to traffic during overload?

If you have an A1 capacity with one v-core, each evaluation cycle quota is 30 seconds
(1*30) of CPU utilization. If the sum of your CPU utilization exceeds the total v-core
quota in your capacity, the capacity enters a temporary interactive request delay mode,
during which each interactive request (such as report load, visual interaction, and so on)
is delayed before it's sent to the engine for execution. The amount of delay is
proportional to the amount of overload detected. Overload of 100% will incur a delay of
20 seconds, while overloads smaller than 10% are allowed.

The capacity stays in interactive request delay mode if the previous evaluation is at
greater than 100% resource usage.

Which operations contribute to interactive

utilization, and which to background utilization?
The following events are interactive operations:

Datasets - Report View, Query, XMLA read

Dataflows
Paginated Report - paginated report render

The following are background operations:

Datasets - scheduled refresh, on-demand refresh, background query (after refresh)

Dataflows - scheduled dataflow refresh
Paginated reports - data driven subscriptions renders
AI

How can I use my utilization data to predict my

capacity needs?
Your metrics report dataset retains 30 to 45 days of data. You can use the report to
indicate how close you're to your capacity's maximum resources, and if you save
monthly snapshots, you can compare them to indicate trends of growth and extrapolate
the rate in which you'll arrive at 100% utilization of your resources.

How can I get notified that I'm approaching my

max capacity?
There are two options for Embedded Premium:

The Capacity management page in the Power BI admin portal has a utilization
notification checkbox. Users can select the threshold at which an alert will be
triggered (the default is 80%), and the email address to which utilization alerts
should be sent.
Configure an Azure Alert using the Premium CPU metric.

How much data is Power BI storing? How can I

retain more?
The Power BI service stores over 90 days of utilization data. Users who need longer data
retention can use Bring Your Own Log Analytics (BYOLA) to store more utilization data,
which will be available for Embedded Premium customers by the Embedded Premium
generally available (GA) date.
How do I use utilization data to perform
chargebacks?
On the left side of the utilization report, a bar chart visual displays utilization
information between workspaces for the time span of the report. The bar chart visual
can be used for chargebacks, providing each workspace represents a different ISV
customer, business unit, cost center, or other entity to which chargebacks can apply.

Technical
Where can I learn more about capacity and SKUs
in Power BI embedded analytics?
Refer to the Capacity and SKUs in Power BI embedded analytics article.

What are the prerequisites for creating a PBIE

capacity in Azure?
Sign-in to your organizational directory (Microsoft accounts aren't supported).
You need to have a Power BI tenant, that is, at least one user in your directory has
signed up for Power BI.
You need to have an Azure subscription in your organizational directory.

How can I monitor Power BI Embedded capacity

consumption?
Using the Power BI Admin portal.

Downloading the Microsoft Fabric Capacity Metrics app in Power BI.

Using Azure diagnostic logging.

Can my capacity scale automatically to adjust to

my app consumption?
While there's no automatic scaling now, all the APIs are available to scale at any time.
Why creating/scaling/resuming a capacity results
in putting the capacity into a suspended state?
Capacity provisioning (scale/resume/create) may fail. You can use the Get Details API to
check a capacity's ProvisioningState: Capacities - Get Details.

Can I only create Power BI Embedded capacities

in a specific region?
With the Multi-geo feature, you can purchase a Power BI Embedded capacity in a
different region than your Power BI home tenant location

Why can't I see a workspace that I have

permission to see?
When a user is granted permissions to a workspace, app, or item, it might not be
immediately available through API calls. The result can either be a missing item in a
'GET' API response, or an error when trying to use the item. The user can resolve this
issue by calling refreshUserPermissions API, which updates the user permissions.

How can I find my PBI tenant region?

You can use the PBI portal to find your PBI Tenant region.

https://app.powerbi.com/ > ? > About Power BI

What does the Cloud Solution Provider (CSP)
channel support?
You can create PBIE for your tenant with subscription type CSP
Partner account can sign in to customer tenant and purchase PBIE for customer
tenant, specify customer tenant user as Power BI capacity admin

Why do I get an unsupported account message?

Power BI requires you to sign up with an organizational account. Trying to sign up for
Power BI using a Microsoft account isn't supported.

Can I use APIs to create and manage Azure

capacities?
Yes, there are PowerShell cmdlets and Azure Resource Manager REST APIs you can use
to create and manage PBIE resources.

Rest APIs
 PowerShell cmdlets

What is the PBI Embedded capacity role in a PBI

Embedded solution?
To promote your solution to production, you need to assign the Power BI content
(workspace) your application uses to a Power BI Embedded (A SKU) capacity.

In what Azure regions is PBI Embedded

available?
Power BI Embedded is non-regional. This means it's not dependent on any specific
Azure region.

See Azure Products by Region for regional information about all Azure products.

What is Power BI Embedded's authentication

model?
Power BI Embedded continues to use Microsoft Entra ID for master user (a designated
Power BI Pro or Premium Per User (PPU) licensed user) authentication, or with service
principal for authenticating the application inside Power BI.

An ISV can implement their own authentication and authorization for their applications.

You can use your existing directory if you already have a Microsoft Entra tenant. You can
also create a new Microsoft Entra tenant for your embedded application content
security.

To get a Microsoft Entra token, use one of the Microsoft Authentication Libraries. There
are client libraries available for multiple platforms.

What object ID is the service principal object ID?

The Object ID from the main screen of a registered app is the object ID for the app.

The object ID found in the Managed application in local directory > Properties section is
the service principal object ID you need to use. This object ID is to reference a service
principal for operations or to make changes to the service principal object ID. Such as
applying a service principal as an admin to a workspace.
How is Power BI Embedded different from other
Azure services?
You must have a Power BI account before purchasing Power BI Embedded in Azure. Your
Power BI Embedded deployed region determines your Power BI account. Manage your
Power BI Embedded resource in Azure to:

Scale up/down
Add capacity admins
Pause/resume service

Use PowerBI.com to assign/un-assign workspaces to your Power BI Embedded capacity.

What is the difference between using row-level

security (RLS) vs. JavaScript filters?
There's often confusion around when to use RLS versus JavaScript filters. One method is
about controlling what a specific user can see, and the other is about optimizing the
user's view.

With RLS, the ISV developer controls the data filtering as part of the model creation and
embed token generation. The end user sees only what the ISV allows the user to see. In
this case, the user can choose to see less than what's being filtered, but won't be able to
bypass the RLS configuration and see more than what's allowed.

With client-side filtering (JavaScript), the ISV might decide what the end user sees in the
initial view, but they can't control changes the end user might apply to the view itself.
Since user JavaScript client code can trigger data filtering on the backend, it can't be
considered secure.

How do I manage permissions for service

principals with Power BI?
Once you enable service principal to use with Power BI, the application's AD permissions
don't take effect anymore. The application's permissions are then managed through the
Power BI admin portal.

Service principals inherit the permissions for all Power BI tenant settings from their
security group. To restrict permissions, create a dedicated security group for service
principals and add it to the Except specific security groups list for the relevant, enabled
Power BI settings.
This situation matters when you add the service principal as an admin to the new
workspace. You can manage this task through the APIs or with the Power BI service.

When should I use an application ID vs. a service

principal object ID?
The application ID, also known as client ID, is used to create the access token when
passing the application ID for authentication.

To reference a service principal for operations or to make changes you use the service
principal object ID — for example, applying a service principal as an admin to a
workspace.

How can I embed a Power BI report that

contains a paginated report visual?
To embed a Power BI report that contains a paginated report visual with the embed for
your customers method, use a service principal and embed the report with a multi-
resource embed token, that contains the following:

Power BI report ID
Paginated report ID (of the report the visual is connected to)
Dataset ID (of the Power BI report)

The service principal must have access to both reports (paginated and Power BI).
Request body example for the generate token call:

JSON

{
"datasets": [
{
"id": "a5d577c7-0568-4180-a6d3-0f6cc0ca3df4"
}
],
"reports": [
{
"allowEdit": false,
"id": "05024421-b4df-483c-a2ce-61202d0323ce"
},
{
"id": "f8612306-f3a8-40e1-a448-d8e05992a007"
}
]
}
 ７ Note

Master user is not supported.

Can you sign into the Power BI service with

service principal?
No - you can't sign into Power BI using service principal.

Also, you can't consume content as a user in external applications (SaaS embed), only
when you generate an embed token.

What are the best practices to improve

performance?
Power BI Embedded performance

Licensing
How do I purchase Power BI Embedded?
Power BI Embedded is available through Azure.

What happens if I already purchased Power BI

Premium and now I want some Power BI
Embedded in Azure benefits?
Customers continue to pay for any existing Power BI Premium purchases until the end of
their current agreement term and then, at that point, may switch their Power BI Premium
purchases as necessary.

Do I still have to buy Power BI Premium to get

access to Power BI Embedded?
No, Power BI Embedded includes the Azure-based capacity that you need to deploy and
distribute your solution to customers.
What's the purchase commitment for Power BI
Embedded?
Customers may change their usage on an hourly basis. There's no monthly or annual
commitment for the Power BI Embedded service.

How does the usage of Power BI Embedded

show up on my bill?
Power BI Embedded bills on a predictable hourly rate based on the type of node(s)
deployed. You're billed as long as your resource is active, even if there's no usage. You
need to pause your resource to stop billing.

Who needs a Power BI Pro or Premium Per User

(PPU) license for Power BI Embedded and why?
You need a Power BI Pro or Premium Per User (PPU) license or service principal to use
REST APIs. To add reports to a Power BI workspace, an analyst needs either a Power BI
Pro or Premium Per User (PPU) license or service principal. To manage Power BI tenant
and capacity, an admin is required have a Power BI Pro or Premium Per User (PPU)
license.

Because Power BI Embedded allows Power BI portal use for managing and validating
embedded content, the Power BI Pro or Premium Per User (PPU) license is required to
authenticate the app inside PowerBI.com to get access to the reports in the right
repositories.

However, for creating/editing embedded reports inside your application, the end user
does not need a Pro or Premium Per User (PPU) license as the user isn't required to be a
Power BI user at all.

Can I get started for free?

Yes, you can use your Azure credits for Power BI Embedded.

Can I get a trial experience for Power BI

Embedded in Azure?
Since Power BI Embedded is a part of Azure, it's possible to use the service with the
$200 credit received when signing up for Azure .
Is Power BI Embedded available for
national/regional clouds (US Government,
Germany, China)?
Power BI Embedded is also available for national/regional clouds.

Is Power BI Embedded available for non-profits

and educational?
There's no special Azure pricing for non-profit and educational entities.

Power BI Workspace Collection

What is Power BI Workspace Collection?
Power BI Workspace Collection (Power BI Embedded Version 1) is a solution based on
the Power BI Workspace Collection Azure resource. This solution allows you to create
Power BI Embedded applications for your customers using Power BI content under the
Power BI Workspace Collection solution, dedicated APIs, and workspace collection keys
to authenticate the application to Power BI.

Is Power BI Workspace Collection on a

deprecation path?
Yes, but customers that are already using the Power BI Workspace Collection solution
can continue to use it until deprecation. Customers can also create new workspace
collections and any Power BI Embedded applications that still use the Power BI
Workspace Collection solution.

However, this also means that new features aren't added to any Power BI Workspace
Collection solutions. We encourage customers to plan their migration to the new Power
BI Embedded solution.

When is Power BI Workspace Collection support

discontinued?
Customers that are already using the Power BI Workspace Collections solution can
continue to use it until the end of their support agreement.
In what regions can I create a PBI Workspace
Collection?
The available regions are Australia Southeast, Brazil South, Canada Central, East US 2,
Japan East, North Central US, North Europe, South Central US, Southeast Asia, UK South,
West Europe, West India, and West US.

Why should I migrate from PBI Workspace

Collection to Power BI Embedded?
There are some Power BI Embedded solution features and capabilities that you can't do
with Power BI Workspace Collection.

Some of the features are:

All the PBI data sources are supported. Only two Power BI Workspace Collection
data sources are supported.
Features such as Q&A, refresh, bookmarks, embedding dashboards & tiles, and
custom menus are only supported in the Power BI Embedded solution.
Capacity billing model.

Embedding setup tool

What is the Embedding setup tool?
The Embedding setup tool allows you to quickly get started and download a sample
application to begin embedding with Power BI.

Which solution should I choose?

Embedding for your customers provides the ability to embed dashboards and
reports to users who don't have an account for Power BI. In the Embedding setup
tool , run the Embed for your customers solution.
Embedding for your organization allows you to extend the Power BI service. In the
Embedding setup tool , run the Embed for your organization solution.

I've downloaded the sample app, which solution

do I choose?
If you're working with the Embed for your customers experience, save and unzip the
PowerBI-Developer-Samples.zip file. Then open the PowerBI-Developer-Samples-

master\App Owns Data folder and run the PowerBIEmbedded_AppOwnsData.sln file.

If you're working with the Embed for your organization experience, save and unzip the
PowerBI-Developer-Samples.zip file. Then open the PowerBI-Developer-Samples-

master\User Owns Data\integrate-report-web-app folder and run the pbi-saas-embed-

report.sln file.

How can I edit my registered application?

To learn how to edit Microsoft Entra registered applications, see Quickstart: Update an
application in Microsoft Entra ID.

How can I edit my Power BI user profile or data?

You can learn how to edit your Power BI data here.

For more information, see Troubleshooting your embedded application.

More questions? Try the Power BI Community

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Power BI Embedded Azure Resource
Manager REST API reference
Article • 10/31/2023

This API provides a RESTful set of web services that enables you to create, retrieve,
update, and delete Power BI dedicated capacities.

See also
Power BI Embedded documentation
Power BI embedding documentation
Power BI REST API reference
Get an Azure AD access token
Using the Power BI REST APIs
Article • 08/31/2023

The Power BI REST APIs provide service endpoints for embedding, administration,
governance and user resources.

With Power BI REST APIs you can do the following:

Manage Power BI content

Perform admin operations

Embed Power BI Content

７ Note

Some of the Power BI APIs refer to workspaces as groups. Any reference to

groups means that you're working with workspaces.

When accessing Power BI REST API, your request and response content and
data may be processed by data centers in regions other than the home region
of your Power BI tenant.

Scopes
To use the Power BI REST APIs, you need to register an Azure Active Directory (Azure
AD) application in Azure. The Azure AD app establishes permissions for Power BI REST
resources, and allows access to the Power BI REST APIs. To learn how to register an app,
see Register an Azure AD application to use with Power BI.

After registering an Azure AD app, you can authenticate against it using either the Azure
AD (v1.0; ADAL) or the Microsoft identity platform (v2.0; MSAL) endpoints. To learn more
about how these authentication methods work, see Why update to Microsoft identity
platform (v2.0)?

For more information about Power BI access permissions, see Permissions and consent
in the Microsoft identity platform endpoint.

Using a service principal

Scopes are not required if you're using a service principal. Once you enable a service
principal to be used with Power BI, the application's AD permissions don't take effect
anymore. When using a service principal, the application's permissions are managed
through the Power BI admin portal. For more information see Enable the Power BI
service admin settings.

Adding scopes
To add permissions to your Azure AD app, follow these steps:

1. Open your App in Azure.

2. From the left, under Manage, select API permissions.

3. Select Add a permission.

4. In the Request API permissions window, select Power BI Service.

5. Select Delegated permissions. A list of APIs is displayed.

6. Expand the API you want to add permissions to, and select the permissions you
want to add to it.

7. Select Add permissions.

Removing scopes
To remove a permissions from your Azure AD app, follow these steps:

1. Open your App in Azure.

2. From the left, under Manage, select API permissions.

3. Select the Context menu (permission ellipsis).

4. Select Remove permission.

Throttling
Power BI uses throttling to maintain optimal performance and reliability. To prevent
overuse of resources from single users, Power BI limits the number of API calls within a
time window per user.
When a user sends a number of requests that exceeds a predetermined limit during a
time window, Power BI throttles any further requests from that user for a short period.

When applications experience throttling, Power BI returns an HTTP status code 429 (Too
many requests) with a Retry-After HTTP header in the response, indicating how many
seconds the calling application has to wait before making a new request.

REST Operation groups

This table lists the Power BI REST API operation groups.

７ Note

To manage Power BI Embedded capacities, use the Power BI Embedded Azure

Resource Manager REST APIs.

Operation group Description

Admin Operations for working with administrative tasks.

Apps Operations for working with Apps.

Available Features Operations that return available features.

Capacities Operations for working with capacities.

Dashboards Operations for working with dashboards.

Dataflow Storage Accounts Operations for working with dataflow storage accounts.

Dataflows Operations for working with dataflows.

Datasets Operations for working with datasets.

Embed Token Operations for working with embed tokens.

Gateways Operations for working with gateways.

Groups Operations for working with groups.

Imports Operations for working with imports.

Pipelines Operations for working with deployment pipelines.

Push Datasets Operations for working with push datasets.

Reports Operations for working with reports.

Operation group Description

Template Apps Operations for working with Template Apps.

Users Operations for working with users.

Next steps
Playground

Power BI embedded analytics documentation

.NET SDK
Push semantic model limitations
Article • 06/04/2024

Push semantic models are very limited in their functionality. They're designed only for a
near real-time streaming scenario to be consumed by a streaming tile in a dashboard,
and not by a Power BI report.
This article lists limitations of the Power BI REST APIs Push semantic models.

Limitations
Review the following list of limitations before using the push semantic models APIs.

75 max columns

75 max tables

10,000 max rows per single POST rows request

1,000,000 rows added per hour per semantic model

5 max pending POST rows requests per semantic model

120 POST rows requests per minute per semantic model

If table has 250,000 or more rows, 120 POST rows requests per hour per semantic
model

200,000 max rows stored per table in FIFO semantic model

5,000,000 max rows stored per table in 'none retention policy' semantic model

4,000 characters per value for string column in POST rows operation

75 max relationships

Doesn't work with service principal profiles

Related content
Power BI REST APIs.
Push semantic models.
Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Semantic model REST API permissions
Article • 11/10/2023

This article describes Power BI permissions in general, and semantic model permissions
in the context of the Power BI REST APIs.

Power BI permissions
Power BI has two sets of permissions:

Workspace permissions

Item 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 semantic models 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 semantic models 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:

Groups - Add Group User - A POST API for adding workspace permissions

Groups - Update Group User - A PUT API for changing workspace permissions

Groups - Get Group Users - A GET API for getting workspace permissions

Item permissions
Power BI items, such as reports, semantic models, 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.

Semantic model permissions and REST APIs

Semantic model permissions are part of the item permissions. The table below lists the
Power BI semantic model 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 Equivalent to Allows the user to share the
read the content build content of the semantic model
of the semantic permissions with other users who will get read,
model reshare, or explore permissions for
it

ReadReshareExplore

ReadReshare

ReadExplore
 Permission Read Explore Reshare

Read

７ Note

To allow a user to perform write operations on a semantic model, 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 semantic
model. 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 semantic model such as with Analyze in Excel.

To access the data via the XMLA endpoint.

Row-level security
For a semantic model that uses row-level security (RLS), any permissions higher than
build will enable the user to view all the data in the semantic model. Build , and

permissions lower than build , will only give the semantic model user access to the data
they're allowed to see as configured in your RLS settings.

Get and update datsemantic modelaset permissions with

APIs
POST APIs let you add new permissions to a semantic model. You can use these
APIs to add permissions for users but not to remove permissions. For example, you
can add the Reshare permission to a user that has the Read permission. However,
 you can't remove the Reshare permission from a user that has both Read and
Reshare permissions, by attempting to add the Read permission.

Datasets - Post Dataset User

Datasets - Post Dataset User In Group

PUT APIs update the user’s permissions to a given dataset. The PUT API can't be
used for changing write permissions or any folder level inherited permissions. This
API also supports removing all permissions for a dataset for a given target.
Datasets - Put Dataset User
Datasets - Put Dataset User In Group

GET APIs return a list of principals that have access to the specified dataset.
Datasets - Get Dataset Users
Datasets - Get Dataset Users In Group

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
Power BI REST APIs.
Push datasets.
Power BI Developer in a Day course
Article • 01/09/2023

The Power BI Developer in a Day video-based course empowers you as an app

developer with the technical knowledge required to embed Power BI content. It
comprises 2 hours 20 minutes of viewable content—available on demand, and is free of
charge. There's also a self-study kit that you can download and use to complete a series
of six hands-on labs.

The course was designed specifically for experienced app developers. So, it's an
advantage if you have development experience with:

ASP.NET
Visual C#
HTML
JavaScript

Familiarity with Power BI will be beneficial, but not essential. We'll introduce you to the
core concepts.

After you complete the course, you'll know how to:

＂ Acquire access using Azure AD apps and tokens

＂ Work with the Power BI REST API
＂ Embed Power BI content in your apps
＂ Integrate Power BI content in your apps using the Power BI JavaScript API
＂ Enforce row-level security (RLS) to ensure app users see the right data
＂ Choose the right license to suit your requirements

Watch the welcome and introduction video to start the course.

７ Note

This video might use earlier versions of Power BI Desktop or the Power BI service.

https://www.youtube-nocookie.com/embed/ZWKfjVzI7mY

Course outline
The course of 21 videos is organized into eight modules. We recommend you watch
the videos in the recorded sequence, starting with video 01 and ending with video 21.
 Introduction
Video 01: Welcome and Course Introduction
Video 02: Self-study Kit
Module 01: Power BI Overview
Video 03: Power BI Overview - Part 1
Video 04: Power BI Overview - Part 2
Video 05: Power BI Overview - Part 3
Video 06: Power BI Overview - Part 4
Module 02: Power BI Embedded Analytics
Video 07: Power BI Embedded Analytics - Part 1
Video 08: Power BI Embedded Analytics - Part 2
Module 03: Configure Permissions
Video 09: Configure Permissions - Part 1
Video 10: Configure Permissions - Part 2
Module 04: Embed Power BI Content
Video 11: Embed Power BI Content - Part 1
Video 12: Embed Power BI Content - Part 2
Module 05: Integrate Content with the Power BI Client APIs
Video 13: Integrate Content with the Power BI Client APIs - Part 1
Video 14: Integrate Content with the Power BI Client APIs - Part 2
Module 06: Configure Data Permissions
Video 15: Configure Data Permissions - Part 1
Video 16: Configure Data Permissions - Part 2
Video 17: Configure Data Permissions - Part 3
Module 07: Automate Solution Management
Video 18: Automate Solution Management - Part 1
Video 19: Automate Solution Management - Part 2
Module 08: Power BI Embedded Analytics Licensing
Video 20: Power BI Embedded Analytics Licensing
Bonus Content
Video 21: Power BI Embedded Analytics Playground

Self-study kit
You can download and set up a self-study kit, which consists of the presentation content
and six hands-on labs. For more information, watch the Self-study Kit video.

To complete the labs, you'll need a Windows PC (Windows 7, or later) and the following
software installed:

The latest version of Power BI Desktop.

 Visual Studio 2015, or later. We recommend Visual Studio 2019 . You can use
Community edition, which is free and suited for learning scenarios. It must have
the ASP.NET and web development workload installed.
A web browser supported by Power BI. We recommend Microsoft Edge.

Follow these steps to get set up:

1. Use this link to download the self-study kit (.zip) locally to your PC.
2. Open the file properties, and then check "unblock" (Windows may flag the file as
potentially untrusted).
3. Extract the file contents to a folder in your file system. We recommend you create a
folder that will be easy to find, perhaps naming it Training. The lab documents will
refer to this location as <CourseFolder>.

Once extracted, you'll have the PowerBIDevIAD folder, and within it you'll find the
following folders:

Lab00A (and all other lab folders). The lab folders contain the lab document and
lab resources, which may include assets and solution files.
MySolution: This folder stores your solution files. The lab instructions will direct
you when to use it.
Presentation: This folder contains the course presentation file, which is available as
a PDF document.

Get started with the kit

We recommend you watch the online course first. You can refer back to the presentation
theory by opening the
<CourseFolder>\PowerBIDevIAD\Presentation\PowerBIDevIAD_Presentation.pdf file.
The presentation includes five lab slides, which indicate when it's time to put the theory
to practice. It also includes many resource links to help you find related content.

When you're ready to commence the first lab, open the

<CourseFolder>\PowerBIDevIAD\Lab00A\PowerBIDevIAD_Lab00A.pdf file. This
document guides you to sign in to the Power BI service and prepare a Power BI report.

７ Note

You're responsible for having your own Power BI account. If you don't already have
one, see Sign up for Power BI as an individual.

Your account must have a Power BI Pro license, or you can still accept a Power BI
Pro Trial license—an offer that can only be accepted once. Also, your account must
 not have depleted the reserve of free embed tokens, available with the Power BI
Pro license.

Consider creating a Power BI account for exclusive use in the labs. You can create a
free account with a public domain like https://outlook.live.com , and then using
it to sign in to Power BI and accept the Power BI Pro Trial license.

Instructor kit
Use this link to download the instructor kit (.zip) locally to your PC. You'll find
classroom setup notes in slide one of the PowerPoint slide deck.

Next steps
For more information related to this article, check out the following resources:

Questions? Try asking the Power BI Community

Suggestions? Contribute ideas to improve Power BI
Monitor Power BI Embedded data
reference
Article • 06/04/2024

See Monitor Power BI Embedded for details on collecting and analyzing monitoring data
for Power BI Embedded.

 Tip

Use the Microsoft Fabric Capacity Metrics app to monitor your capacity.

Metrics
This section lists all the automatically collected platform metrics for Power BI Embedded.

ﾉ Expand table

Metric Type Resource Provider / Type Namespace

and link to individual metrics

Capacities Microsoft.PowerBIDedicated/capacities

Capacities
Resource provider and type: Microsoft.PowerBIDedicated/capacities

ﾉ Expand table

Name Metric Unit Description

CPU cpu_metric Percent CPU utilization.

CPU Per cpu_workload_metric Percent CPU utilization per workload.

Workload

Overload overload_metric 0/1 Resource overload, 1 if resource is

overloaded, otherwise 0.

Metric dimensions
Power BI Embedded doesn't have any metrics that contain dimensions.

For information about metric dimensions, see Multi-dimensional metrics.

Resource logs
This section lists the types of resource logs you can collect for Power BI Embedded.

For reference, see a list of all resource logs category types supported in Azure Monitor.

This section lists all the resource log category types collected for Power BI Embedded.

ﾉ Expand table

Resource Log Type Resource Provider / Type Namespace

and link to individual metrics

Capacities Microsoft.PowerBIDedicated/capacities

Azure Monitor Logs tables

This section refers to all of the Azure Monitor Logs Kusto tables relevant to Power BI
Embedded and available for query by Log Analytics.

ﾉ Expand table

Resource Type Notes

Power BI Embedded See the following list of tables.

Power BI Embedded

ﾉ Expand table

Table Description

AzureActivity Entries from the Azure Activity log that provides insight into any subscription-
level or management group level events that have occurred in Azure.

AzureDiagnostics Stores resource logs for Azure services that use Azure Diagnostics mode.
Resource logs describe the internal operation of Azure resources.

AzureMetrics Metric data emitted by Azure services that measure their health and
performance.
For a reference of all Azure Monitor Logs and log analytics tables, see the Azure Monitor
Log table reference.

Activity log
You can select Engine and the AllMetrics categories or either.

Engine
The engine category instructs the resource to log the events listed in the following table.
For each event, there are properties.

ﾉ Expand table

Event Name Event Description

Audit Login Records all new connection to the engine events since the trace started.

Session Initialize Records all session initialization events since the trace started.

Vertipaq Query Begin Records all VertiPaq SE query begin events since the trace started.

Query Begin Records all query begin events since the trace started.

Query End Records all query end events since the trace started.

Vertipaq Query End Records all VertiPaq SE query end events since the trace started.

Audit Logout Records all disconnect from engine events since the trace started.

Error Records all engine error events since the trace started.

Event example
The following table shows an event example.

ﾉ Expand table

Property Name Vertipaq Query End Example Property Description

EventClass XM_SEQUERY_END Event Class is used to categorize

events.

EventSubclass 0 Event Subclass provides

additional information about
Property Name Vertipaq Query End Example Property Description

each event class. (for example, 0:

VertiPaq Scan)

RootActivityId ff217fd2-611d-43c0-9c12-19e202a94f70 Root activity ID.

CurrentTime 2018-04-06T18:30:11.9137358Z Time at which the event started

when available.

StartTime 2018-04-06T18:30:11.9137358Z Time at which the event started

when available.

JobID 0 Job ID for progress.

ObjectID 464 Object ID

ObjectType 802012 ObjectType

EndTime 2018-04-06T18:30:11.9137358Z Time at which the event ended.

Duration 0 Amount of time (in milliseconds)

taken by the event.

SessionType User Session type (what entity caused

the operation).

ProgressTotal 0 Progress total.

IntegerData 0 Integer data.

Severity 0 Severity level of an exception.

Success 1 1 = success. 0 = failure (for

example, a 1 means success of a
permissions check and a 0 means
a failure of that check).

Error 0 Error number of a given event.

ConnectionID 3 Unique connection ID.

DatasetID 5eaa550e-06ac-4adf-aba9-dbf0e8fd1527 ID of the semantic model in

which the statement of the user is
running.

SessionID 3D063F66-A111-48EE-B960- Session GUID.

141DEBDA8951

SPID 180 Server process ID. This process ID

uniquely identifies a user session.
This ID directly corresponds to
the session GUID used by XML/A.
 Property Name Vertipaq Query End Example Property Description

ClientProcessID null The process ID of the client

application.

ApplicationName null Name of the client application

that created the connection to
the server.

CapacityName pbi641fb41260f84aa2b778a85891ae2d97 The name of the Power BI

Embedded capacity resource.

AllMetrics
Checking the AllMetrics option logs the data of all the metrics that you can use with a
Power BI Embedded resource.

The following table lists the operations related to Power BI Embedded that might appear
in the Activity log.

Schemas
Power BI Embedded uses the Power BI Dedicated schema.

Example script for scaling a capacity

To scale a capacity resource, you can use the ScaleUp-Automation-RunBook.ps1
PowerShell RunBook script.

The script uses Power BI and ARM REST APIs that are called in Azure Automation and
triggered by Azure alert.

You can either copy the script, or download it as part of the PowerBI-Developer-
Samples repository, by selecting the green code button, and downloading the ZIP.

Related content
Monitor Azure Power BI Embedded
Azure resource diagnostic logging
Set-AzureRmDiagnosticSetting
Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

az powerbi
Reference

７ Note

This reference is part of the powerbidedicated extension for the Azure CLI (version
2.56.0 or higher). The extension will automatically install the first time you run an az
powerbi command. Learn more about extensions.

Manage PowerBI resources.

Commands
ﾉ Expand table

Name Description Type Status

az powerbi embedded- Manage PowerBI embedded capacity. Extension Preview

capacity

az powerbi embedded- Create a new PowerBI embedded capacity. Extension Preview

capacity create

az powerbi embedded- Delete the specified PowerBI embedded Extension Preview

capacity delete capacity.

az powerbi embedded- List all the embedded capacities for the Extension Preview
capacity list given resource group.

az powerbi embedded- List eligible SKUs for a PowerBI Dedicated Extension Preview
capacity list-sku resource.

az powerbi embedded- Get details about the specified PowerBI Extension Preview
capacity show embedded capacity.

az powerbi embedded- Update the specified PowerBI embedded Extension Preview

capacity update capacity.

az powerbi embedded- Place the CLI in a waiting state until a Extension Preview
capacity wait condition is met.

az powerbi list-auto-scale-v- List all the auto scale v-cores for the given Extension GA
core resource group.
az powerbi list-auto-scale-v-core

List all the auto scale v-cores for the given resource group.

Azure CLI

az powerbi list-auto-scale-v-core [--resource-group]

Optional Parameters

--resource-group -g

Name of resource group. You can configure the default group using az configure --
defaults group=<name> .

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and

examples.
--subscription

Name or ID of subscription. You can configure the default subscription using az

account set -s NAME_OR_ID .

--verbose

Increase logging verbosity. Use --debug for full debug logs.

６ Collaborate with us on
GitHub Azure CLI feedback
Azure CLI is an open source project.
The source for this content can
Select a link to provide feedback:
be found on GitHub, where you
can also create and review
 Open a documentation issue
issues and pull requests. For
more information, see our
 Provide product feedback
contributor guide.
Glossary for Power BI developers
Article • 01/09/2024

Power BI may introduce terminology that is unfamiliar or confusing. This glossary is a

great place to look up terminology, you might even want to keep it bookmarked. Other
great resources for learning about the building blocks that make up Power BI are Power
BI service basic Concepts and Basic concepts for designers. These articles give a high-
level overview of the Power BI pieces and how they're connected.

This glossary is a community effort. Don't see a word here? Ask us to add it (you can use
the documentation feedback button at the bottom of this article).

Account
Use your work or school account to sign in to Power BI. Administrators manage work or
school accounts in Microsoft Entra ID. Your level of access is determined by the Power BI
license associated with that account and the capacity type where content is stored. See
license and Premium, below.

Admin portal
The location where Power BI admins manage users, features, and settings for Power BI in
their organization. (Note: Microsoft 365, Azure, and PowerApps use admin center.)

Aggregates
When the values of multiple rows are grouped together as input on criteria to form a
single value of more significant meaning or measurement. Only implicit measures (see
definition below) can be aggregated.

Aggregation
The reduction of rows in underlying data sources to fit in a model. The result is an
aggregate.

Alert, alerts
A feature that notifies users of changes in the data based on limits they set. Alerts can
be set on tiles pinned from report visuals. Users receive alerts on the service and on
their mobile app.

Annotate
To write lines, text, or stamps on a snapshot copy of a tile, report, or visual on the Power
BI mobile app for iOS and Android devices.

App, apps
A bundle of dashboards, reports, and semantic models. It also refers to the mobile apps
for consuming content, such as Power BI app for iOS.

AppSource
Centralized online repository where you can browse and discover dashboards, reports,
semantic models, and apps to download.

ArcGIS for Power BI

ArcGIS is a mapping and analytics platform created by the company ESRI. The name of
the visual included in the Power BI visuals library is called ArcGIS for Power BI.

Artifacts
See item

Auto Insights
Auto insights are now called Quick Insights.

Microsoft Entra ID, Microsoft Entra ID

The identity service in Microsoft Azure that provides identity management and access
control capabilities through a REST-based API.

Azure Key Vault

The pay-as-you-go security solution that uses a single location (the vault) in Azure to
store, secure and manage cryptographic keys and secrets that can then be invoked by
URI and used by applications for small, high-value security data, such as authentication
keys, storage account keys, data encryption keys, .pfx files, and passwords.

BI, business intelligence

Bookmark
A view of data captured in the Bookmarks pane of a report in Power BI Desktop or
service. In Desktop, the bookmarks are saved in the .pbix report file for sharing on the
Power BI service

Breadcrumbs
The navigation at the top left to quickly navigate between reports and dashboards.

Capacity
A capacity is a dedicated set of resources reserved for exclusive use. It offers
dependable, consistent performance for your content.

Card (visual type)

A Power BI visual type.

Card (Power BI Home)

Power BI Home displays rectangular and square pictures that represent dashboards,
reports, apps, and more. These pictures are referred to as cards.

Certified custom visual

A Power BI custom visual that has met requirements and passed strict security testing.
Connect live
A method of connecting to SQL Server Analysis Services data models. Also called a live
connection.

Connector
Power BI Desktop includes an ever-growing collection of data connectors that are built
to connect to a specific data source. Examples include: GitHub, MailChimp, Power BI
dataflows, Google Analytics, Python, SQL Server, Zendesk, and more than 100 other data
sources.

Container
The areas on the navigation pane are containers. In the nav pane you'll find containers
for: Favorites, Recent, Apps, Shared with me, and Home.

Content
Content for the Power BI service is generally dashboards, reports, and apps. It can also
include workbooks and semantic models.

Content list
The content index for an app.

Content view
The view in Windows Explorer that displays the most relevant content for each item
based on its file name extension or Kind association.

Continuous variable
A continuous variable can be any value between its minimum and maximum limits,
otherwise it's a discrete variable. Examples are temperature, weight, age, and time.
Continuous variables can include fractions or portions of the value. The total number of
blue skateboards sold is a discrete variable since we can't sell half a skateboard.

Correlation
A correlation tells us how the behaviors of things are related. If their patterns of increase
and decrease are similar, then they're positively correlated. And if their patterns are
opposite, then they're negatively correlated. For example, if sales of our red skateboard
increase each time we run a tv marketing campaign, then sales of the red skateboard
and the tv campaign are positively correlated.

Cross-filter
Applies to visual interactions. Cross-filtering removes data that doesn't apply. For
example, selecting Moderation in the doughnut chart cross-filters the line chart. The line
chart now only displays data points that apply to the Moderation segment.

Cross-highlight
Applies to visual interactions. Cross-highlighting retains all the original data points but
dims the portion that doesn't apply to your selection. For example, selecting
Moderation in the doughnut chart cross-highlights the column chart. The column chart
dims all the data that doesn't apply to the Moderation segment, and highlights all the
data that does apply to the Moderation segment.

Custom visual
Visuals that are created by the community and Microsoft. They can be downloaded from
the Office store for use in Power BI reports. You can also develop your own personalized
custom visual.

Dashboard
In the Power BI service, a dashboard is a single page, often called a canvas, that uses
visualizations to tell a story. Because it's limited to one page, a well-designed dashboard
contains only the most important elements of that story. Dashboards can only be
created and viewed in the Power BI service, not in Power BI Desktop. For more
information, see basic concepts, dashboards.

Data connector
See connectors
Data model, Excel Data Model
In Power BI content, a data model refers to a map of data structures in a table format.
The data model shows the relationships that are being used to build databases. Report
designers, administrators, and developers create and work with data models to create
Power BI content.

Dataflow
Dataflows ingest, transform, integrate, and enrich big data by defining data source
connections, ETL logic, refresh schedules, and more. Formerly data pool.

Semantic model
A collection of data used to create visualizations and reports.

DAX expression
Data Analysis Expressions. A Microsoft formula language used to build formulas and
expressions in Power BI Desktop, Azure Analysis Services, SQL Server Analysis Services,
and Power Pivot in Excel.

Desktop or Power BI Desktop

Free Power BI tool used primarily be report designers, admins, and developers.

Diamond
Power BI Premium. The shape of the icon that signifies a workspace is a Premium
capacity workspace.

Dimension
Dimensions are categorical (text) data. A dimension describes a person, object, item,
products, place, and time. In a semantic model, dimensions are a way to group measures
into useful categories. For our skateboard company, some dimensions might include
looking at sales (a measure) by model, color, country/region, or marketing campaign.

Drill up, drill down, drill through

In Power BI, "drill down" and "drill up" refer to the ability to explore the next level of
detail in a report or visual. "Drill through" refers to the ability to select a part of a visual
and be taken to another page in the report, filtered to the data that relates to the part
of the visual you selected on the original page. Drill to details commonly means to show
the underlying records.

Editing View
The mode in which report designers can explore, design, build, and share a report.

Effective identity
The identity used by the generate token API to generate a token for an individual user,
depending on that user's credentials in the app. It could be a master user or service
principal.

Ellipsis
Three dots - ... Selecting an ellipsis displays more menu options. Also referred to as the
More actions menu.

Embed code
A common standard across the internet. In Power BI, the customer can generate an
embed code and copy it to place content such as a report visual on a website or blog.

Embed token
A string of encrypted characters that is used for authentication, which specifies the
content the web app user can access and the user’s access level.

Embedded
See Power BI Embedded.

Embedding
In the Power BI developer offering, the process of integrating analytics into apps using
the Power BI REST APIs and the Power BI SDK.

Environment
[Power BI Desktop, Power BI Mobile, the Power BI service, etc.] Another way to refer to
one of the Power BI tools. It's okay to use Power BI environment (tenant) in
documentation where it may help business analysts who are familiar with the term
tenant to know it's the same thing.

Explicit measures
Power BI uses explicit measures and implicit measures (see definition below). Explicit
measures are created by report designers and saved with the semantic model. They're
displayed in Power BI as fields, and can therefore be used over and over. For example, a
report designer creates an explicit measure TotalInvoice that sums all invoice amounts.
Colleagues who use that semantic model and who have edit access to the report, can
select and use that field to create a visual. When an explicit measure is added or
dragged onto a report canvas, Power BI doesn't apply an aggregation. Creating explicit
measures requires edit access to the semantic model.

Favorite, unfavorite
Verb meaning to add to the Favorites list for quick access to frequently visited
dashboards and reports in Power BI. When you no longer want them as a favorite, you
unfavorite them.

Filter versus highlight

A filter removes data that doesn't apply. A highlight grays out the data that doesn't
apply.

Focus mode
Use focus mode to pop out a visual or tile to see more detail. You can still interact with
the visual or tile while in focus mode.
Free account
See account

Full screen, full-screen mode

Use full screen mode to view Power BI content without the distraction of menus and
navigation panes. Full screen mode is sometimes referred to as TV mode.

Gateways or on-premises data gateways

A bridge to underlying data sources. It provides quick and secure data transfer between
the Power BI service and on-premises data sources that support refresh. Managed by IT.

High-density visuals
Visuals with more data points than Power BI can render. Power BI samples the data to
show the shape and outliers.

Home
The default landing page for Power BI service users. Doesn't modify anything. Can be
called Power BI Home or simply Home.

Inline frame, IFrame

An IFrame is component of an HTML element that allows you to embed reports and
other items inside your app. It's essentially a way to display a secondary webpage inside
the main page.

Implicit measures
Power BI uses implicit measures and explicit measures (see definition above). Implicit
measures are created dynamically. For example, when you drag a field onto the report
canvas to create a visual. Power BI automatically aggregates the value using one of the
built-in standard aggregations (SUM, COUNT, MIN, AVG, etc.). Creating implicit
measures requires edit access to the report.

Independent Software Vendor, ISV

A third-party software developer. An ISV can be an individual or an organization that
independently creates computer software.

Insights
See quick insights.

Item
A component type of the Power BI workspace that includes dashboards, reports,
semantic models, and data flows. Formerly known as artifacts.

KPIs
Key performance indicators. A type of visual.

Left navigation (left nav)

The controls along the left edge of Power BI service.

License
Your level of access is determined by the Power BI license associated with your account
and the capacity type where content is stored. For example, in shared capacity, a user
with a Power BI Pro license can collaborate only with users who are also assigned a Pro
license. In shared capacity, a free license enables access to only the user’s personal
workspace. However, when content is in Premium capacity or Fabric F64 or greater
capacity, users with a Pro license can share that content with users who are assigned a
free license.

A license is assigned to a user and can be a free or Pro license. Depending on how the
license was acquired, it may be paid or unpaid. The accounts are either: per-user or
organizational. Per-user accounts are available as free or Pro. A Power BI free user is
either using stand-alone Power BI Desktop or is using Power BI service stand-alone or is
using Power BI service within an organization that has a Premium organizational
subscription. The Power BI per-user Pro account is a paid monthly subscription that
allows for collaboration and sharing of content with other Pro users.

The organizational Premium (also known as Premium capacity) subscription adds a layer
of features on top of per-user licenses. For example, free per-user account holders
within an organization that has a Premium subscription, are able to do much more with
Power BI than free users without Premium. For example, free users in Premium
organizational accounts, can collaborate with colleagues and can view content that's
hosted on Power BI Premium capacity.

List page or content list

One of the section pages for the elements in the nav pane. For example, Favorites,
Recents, My workspace, etc.

Measure
A measure is a quantitative (numeric) field that can be used to do calculations. Common
calculations are sum, average, and minimum. For example, if our company makes and
sells skateboards, our measures might be number of skateboards sold and average
profit per year.

Mobile app
Apps that allow you to run Power BI on iOS, Android, and Windows devices.

Modeling
[Power BI Desktop] Getting the data you've connected to ready for use in Power BI.
Modeling includes creating relationships between tables in multiple data sources,
creating measures, and assigning metrics.

My workspace
The workspace for each Power BI customer to use to create content. If a customer wants
to bundle anything created here into an app, and they have designer permissions, they
upload it to the appropriate workspace or create a new one.

Native
Included with the product. For example, Power BI comes with a set of native visualization
types. But you can also import other types, such as Power BI visuals.

Navigation pane or nav pane

The controls along the left edge of the Power BI service.

Notification
Messages sent by and to the Power BI Notification Center.

Notification Center
The location in the service where messages are delivered to users, such as notice of
sunsetting certain features.

OneDrive for work or school vs OneDrive

OneDrive is a personal account and OneDrive for work or school is for work accounts.

On-premises
The term used to distinguish local computing (in which computing resources are located
on a customer's own facilities) from cloud computing.

PaaS
PaaS stands for platform as a service. For example, Power BI Embedded.

Page
Reports have one or more pages. Each tab on the report canvas represents a page.

Paginated reports
Paginated reports are designed to be printed or shared. They're called paginated
because they're formatted to fit well on a page. They display all the data in a table, even
if the table spans multiple pages. You can control their report page layout exactly. Power
BI Report Builder is the standalone tool for authoring paginated reports.

PBIVIZ
The file extension for a Power BI custom visual.

PBIX
The file extension for a Power BI Desktop file.

Permissions
What a user can and can't do in Power BI is based on permissions. As a consumer you
won't have the same permissions as a designer, administrator, or developer.

Phone report
The name for a Power BI report that's been formatted for viewing on the phone.

Phone view
The user interface in the Power BI service for laying out a phone report.

Pin, unpin
The action a report designer takes of placing a visual, usually from a report, onto a
dashboard.

Power BI Desktop
Also referred to as Desktop. The free Windows application of Power BI you can install on
your local computer that lets you connect to, transform, and visualize your data. Used by
report designers and admins. For more information, see What is Power BI.

Power BI Embedded
A product used by developers to embed Power BI dashboards and reports into their
own apps, sites, and tools.

Power BI Premium
An add-on to the Power BI Pro license that enables organizations to predictably scale BI
solutions through the purchasing of reserved hardware in the Microsoft cloud. See
account.

Power BI Pro
A monthly per-user license that provides the ability to build reports and dashboards,
collaborate on shared data, keep data up-to date automatically, audit and govern how
data is accessed and used, and the ability to package content to distribute (Power BI
apps). See account.

Power BI Report Builder

A free, standalone Windows Desktop application used for authoring paginated reports.
Used by report designers. For more information, see Power BI Report Builder. Power BI
Report Builder can be downloaded from the Power BI site.

Power BI Report Server

An on-premises report server with a web portal in which you display and manage
reports and KPIs. It allows organizations to build distributed, hybrid BI systems (a mix of
cloud and on-premises deployments).

Power BI service
An online SaaS (Software as a service) service. For more information, see What is Power
BI.

Power BI tenant
A Power BI account for an organization which has its data stored separately from other
organizations but which is accessed through a shared service.

Premium workspace
A workspace running in a capacity, signified to customers by a diamond icon.

Pro license or Pro account

See account.

Publish
Power BI service report designers bundle the contents of a Power BI workspace to make
it available to others as a Power BI app. Power BI Desktop report designers use publish
to refer to sending a Power BI Desktop report in .pbix format to the Power BI service so
that they can build dashboards from it and easily share it with others.

Q&A
The ability to type natural language questions about a semantic model and get
responses in the form of visualizations. Appears in the Power BI service and Desktop.

Q&A virtual analyst

[Power BI Mobile] For iOS, the conversational UI for Q&A.
QR codes
[Power BI Mobile] A matrix barcode that can be generated for dashboards or tiles in the
Power BI service to identify products. QR codes can be scanned with a QR code reader,
or with the Power BI Mobile app on iOS or Android, to link directly to the dashboard or
tile.

Query string parameter

Add to a URL to pre-filter the results seen in a Power BI report. In the broadest sense, a
query string recovers information from a database.

Quick Insights
Quick Insights refer to automatically generated insights that reveal trends and patterns
in data.

R, Microsoft R
A programming language and software environment for statistical computing and
graphics.

Reading View
Read-only view for reports (as opposed to Editing View).

Real-time streaming
The ability to stream data and update dashboards in real time from sources such as
sensors, social media, usage metrics, and anything else from which time-sensitive data
can be collected or transmitted.

Recent
The container in the nav pane that holds all the individual items (reports, dashboards,
etc.) that were accessed last.
Related content
Shows the individual pieces of content that contribute to the current content. For
example, for a dashboard, you can see the reports and semantic models providing the
data and visualizations on the dashboard.

Relative links
Links from dashboard tiles to other dashboards and reports that have been shared
directly or distributed through a Power BI app. This enables richer dashboards that
support drill through.

Report
A multi-perspective view into a single semantic model, with visualizations that represent
different findings and insights from that semantic model. It can have a single
visualization or many, a single page or many pages.

Report editor
The report editor is where new reports are created and changes are made to existing
reports by report designers.

Report measures
Also called custom calculations. Excel calls these calculated fields. See also measures.

Responsive visuals
Visuals that change dynamically to display the maximum amount of data and insights,
no matter the screen size.

Row-level security, RLS

Power BI feature that enables database administrators to control access to rows in a
database table based on the characteristics of the user executing a query (for example,
group membership).

Administrators can configure RLS for data models imported into Power BI with Power BI
Desktop.
S

SaaS
Software as a service (or SaaS) is a way of delivering applications over the internet—as a
web-based service. Also referred to as: web-based software, on-demand software, or
hosted software.

Scalability
The capability of a piece of hardware or software or network to expand or shrink to
meet future needs and circumstances.

Screenshot
Simple screenshots of a report can be emailed using the send a screenshot feature.

Service
See Power BI service A standalone resource available to customers by subscription or
license. A service is a product offering delivered exclusively via the cloud.

Service principal
An identity created for use with applications, hosted services, and automated tools to
access Azure resources. The service principal tokens can be used to authenticate and
grant access to specific Azure resources from a user-app, service or automation tool,
when an organization is using Microsoft Entra ID.

It can sometimes replace the master user to authenticate with Power BI.

Settings
The location for Power BI users to manage their own general settings, such as whether
to preview new features, set the default language, close their account, etc. Also, users
manage individual settings for content assets, alerts, and subscriptions. Represented by
a cog icon.

Share, sharing
In Power BI, sharing typically means directly sharing an individual item (a dashboard or
report) with one or more people by using their email address. Requires a Power BI Pro
license for sender and recipient. On mobile devices, share can refer to native OS share
functionality, such as "annotate and share."

Shared with me
The container in the nav pane that holds all the individual items that were directly
shared by another Power BI user.

Single sign-on, SSO

An authentication process that permits a user to log on to a system once with a single
set of credentials to access multiple applications or services.

Snapshot
In Power BI, a snapshot is a static image vs. a live image of a tile, dashboard, or report.

SQL Server Analysis Services (SSAS)

An online analytical data engine used in decision support and business analytics,
providing the analytical data for business reports and client applications such as Power
BI, Excel, Reporting Services reports, and other data visualization tools.

SQL Server Reporting Services (SSRS)

A set of on-premises tools and services to create, deploy, and manage report servers
and paginated reports.

Streaming data
See real-time streaming.

Subscriptions, Subscribe
You can subscribe to report pages, apps, and dashboards and receive emails containing
a snapshot. Requires a Power BI Pro license.

Summarization
[Power BI Desktop] The operation being applied to the values in one column.

Tenant
A client organization that is served from a web service (SaaS) which also serves other
client organizations, and each organization’s data is stored in a separate database.

Tiles
A tile is a snapshot of your data, pinned to the dashboard. A tile can be created from a
report, semantic model, dashboard, the Q&A box, Excel, SQL Server Reporting Services
(SSRS) reports, and more.

Time series
A time series is a way of displaying time as successive data points. Those data points
could be increments such as seconds, hours, months, or years.

User Principal Name (UPN)

A format used to specify an internet-style name, such as
[email protected]. The format consists of a login name and domain
separated by the @ symbol.

Value, values
Numerical data to be visualized.

Visual, visualization
A chart. Some visuals are: bar chart, treemap, doughnut chart, map.
Visual interaction
One of the great features of Power BI is the way all visuals on a report page are
interconnected. If you select a data point on one of the visuals, all the other visuals on
the page that contain that data change, based on that selection.

Visualizations pane
Name for the visualization templates that ship in the shared report canvas for Power BI
Desktop and the Power BI service. Contains small templates, also called icons, for each
native visualization type.

Workbook
An Excel workbook to be used as a data source. Workbooks can contain a data model
with one or more tables of data loaded into it by using linked tables, Power Query, or
Power Pivot.

Workspace
Containers for dashboards, reports, and datasets in Power BI. Users can collaborate on
the content in any workspace except My workspace. The contents can be bundled into a
Power BI app. Those stored in Premium capacity or Fabric F64 or greater capacity can be
shared with Free users. Personal workspaces (under My workspace) can be hosted in
Premium capacity.

X-axis
The axis along the bottom, the horizontal axis.

Y-axis
The axis along the side, the vertical axis.

Related content
Basic concepts for Power BI service consumer
Basic concepts for designers

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Ask the community

Power BI Dev Camp
Article • 11/05/2023

Power BI Dev Camp (third-party site) is an educational resource for developers who
want to learn more about Power BI as a developer platform. It covers topics such as
Power BI embedding and the development of Power BI visuals and custom connectors.

This article provides links to some of the Power BI Dev Camp resources.

Tutorials
The Power BI Dev Camp tutorials are targeted toward developers who are interested in
understanding how to embed Power BI items (such as reports, dashboards and tiles) and
do other basic embedding tasks.

App-owns-data tutorials

App-owns-data embedding with .NET 5 - A tutorial that shows developers

how to create a .NET 5 MVC web application that implements Power BI
embedding that uses the app-owns-data embedding model. The tutorial
covers advanced topics such as adding project support for TypeScript by using
node.js , and programming the Power BI REST API to generate multi-resource

access tokens.

Tabular-Object-Model-Tutorial - A tutorial and sample code programming

semantic model that use the Tabular Object Model with Power BI Desktop and the
Power BI service via the XMLA endpoint.

PowerBI-PowerShell-Tutorial - Student files for the Power BI PowerShell tutorial

from Power BI Dev Camp.

Examples
The Power BI Dev Camp examples provide additional resources for developers who are
looking to embed Power BI items (such as reports, dashboards and tiles).

App-owns-data examples
 App-owns-data hello world - A minimal .NET 5 application example to
embed either a standard Power BI report or a paginated report. You can run
and test the code in either Visual Studio Code or Visual Studio 2019. It also
includes details for updating the settings for URLs and Azure ID resource IDs
when you use a Power BI cloud other than the public cloud.

App-owns-data custom web API - A .NET 5 custom web API example, with a
single-page application (SPA) client created by using JavaScript. The custom
web API interacts with the Power BI service API as a service principal, and
returns embedding data and embed tokens to the client. This example
demonstrates collecting telemetry from the SPA client and storing it in a
custom database to monitor report loading performance.

App-owns-data and RLS - An example of a web application built by using

.NET 5 and Power BI app-owns-data embedding. Created to demonstrate how
to design a security authorization model that uses EffectiveIdentity and
row-level security (RLS).

App-owns-data multitenant - An example of a developer project

demonstrating how to use service principal profiles to manage a multitenant
environment with Power BI and app-owns-data embedding.

Salesforce app-owns-data embedding - An example of a project that

demonstrates how to implement app-owns-data embedding with Power BI
reports. This project has been created by using the Salesforce developer
experience (SFDX) and the Salesforce command-line interface (CLI). The goal
of this example is to provide guidance and demonstrate best practices for
developers who need to implement Power BI embedding in a Salesforce
environment.

Tenant management application for Power BI - A .NET 5 sample application that

demonstrates how to manage service principals within a large-scale Power BI
embedding environment with thousands of customer tenants.

Videos
To view Power BI Dev Camp videos, go to the video page .

Presentations
To download Power BI Dev Camp presentations, go to the Camp-Sessions GitHub
repository.

Next steps
Embed Power BI content into an application for your customers
Embed Power BI content into an application for your organization
Embed a Power BI report in an application for your organization
Power BI embedded analytics playground

More questions? Try the Power BI Community .

Power BI embedded analytics Client
APIs
A client side library for embedding Power BI using JavaScript or TypeScript.

Get started

ｅ OVERVIEW

What is Power BI embedded analytics?

Understanding the different embedding solutions

ｂ GET STARTED

Embed a report

Embed a report visual

Embed a paginated report

Embed a dashboard

Embed a Power BI item in a Jupyter notebook

Embed a Power BI item in a React application

Client APIs

ｐ CONCEPT

How to handle events

Refresh the access token

Use bootstrap for better performance

ｃ HOW-TO GUIDE

Control report filters

Configure report settings

Create, edit, and save a report

Report bookmarks

Personalize a report layout

Optimize a Power BI report for mobile layout

References and resources

ｉ REFERENCE

Power BI embedded analytics playground

Power BI Client on GitHub

Power BI Report Authoring on GitHub

Power BI embedded analytics documentation

Developer samples and scripts

Embedding setup tool

Stack Overflow

Power BI REST APIs