Considerations when generating an embed token

Generate token is a REST API that lets you generate a token for embedding a Power BI item in a web app or a portal. 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 only applicable when you're embedding for your customers (also known as the app owns data scenario).

You can use the following APIs to generate a token:

Workspace versions

Power BI has two workspace versions, a classic workspace, and a new workspace. You can learn more about the differences between these workspaces in new and classic workspace differences.

When creating an embed token, different workspaces have different considerations and require different permissions.

Classic workspace New workspace
Considerations
  • The dataset and the item must be in the same workspace
  • Service principal cannot be used
  • The dataset and the item can be in two different new workspaces
    Workspace permissions The master user must be an admin of the workspace The service principal or master user must be at least a member of both workspaces

    Note

    • You cannot create an embed token for My workspace.
    • The word item refers to a Power BI item such as a dashboard, tile, Q&A or report.

    Securing your data

    When creating your solution, consider these two approaches for securing your data: Workspace-based isolation and Row-level security-based isolation. You can find a detailed comparison between them in Multi-tenancy solutions with Power BI embedded analytics.

    If you're going to use the RLS approach, review the RLS considerations and limitations at the end of this article.

    Token permissions

    In the generate token APIs, the GenerateTokenRequest section describes the token permissions.

    Note

    The token permissions listed in this section are not applicable for the Generate token for multiple reports API.

    Access Level

    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).

      If you're using the Generate token for multiple reports API, use the allowEdit parameter to grant the user viewing and editing permissions.

    • Create - Grant the user permissions to create a report (only applies when generating an embed token for creating a report).

      For report creation, you must also supply the datasetId parameter.

    Saving a copy of the report

    Use the allowSaveAs boolean to let users save the report as a new report. This setting is set to false by default.

    This parameter is only applicable when generating an embed token for a report.

    Row Level Security

    With Row Level Security (RLS), you can choose to use a different identity than the identity of the service principal or master user you're generating the token with. Using this option, 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 in some cases leave out the user's identity (the EffectiveIdentity parameter). This allows the token to have access to the entire database. This method can be used to grant access to users such as admins and managers, who have the permissions to view the entire dataset. However, you cannot 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.

    RLS type Can I generate an embed token without specifying the effective user ID? Considerations and limitations
    Cloud Row Level Security (Cloud RLS) ✔ Master user
    ✖ Service principal
    RDL (paginated reports) ✖ Master user
    ✔ Service principal
    You cannot use a master user to generate an embed token for RDL.
    Analysis Services (AS) on premises live connection ✔ Master user
    ✖ Service principal
    The user generating the embed token also needs one of the following permissions:
  • Gateway admin permissions
  • Datasource impersonate permission (ReadOverrideEffectiveIdentity)
  • Analysis Services (AS) Azure live connection ✔ Master user
    ✖ Service principal
    The identity of the user generating the embed token cannot be overridden. Custom data can be used to implement dynamic RLS or secure filtering.

    Note: Service principal must provide its object ID as the effective identity (RLS username).
    Single Sign On (SSO) ✔ Master user
    ✖ Service principal
    An explicit (SSO) identity can be provided using the identity blob property in an effective identity object
    SSO and cloud RLS ✔ Master user
    ✖ Service principal
    You must provide the following:
  • Explicit (SSO) identity in the identity blob property property in an effective identity object
  • Effective (RLS) identity (username)
  • Note

    Service principal must always provide the following:

    • An identity for any item with an RLS dataset.
    • For an SSO dataset, an effective RLS identity with the username property defined.

    Next steps