Embed Token - Generate Token

Service:
Power BI REST APIs
API Version:
v1.0

Generates an embed token for multiple reports, datasets and target workspaces. Reports and datasets do not have to be related. The binding of a report to a dataset can be done during embedding. Creating a report can only be done in workspaces specified in targetWrokspaces.

This API is relevant only to 'App owns data' embed scenario. For more information about using this API, see Considerations when generating an embed token.

Required scope:

  • Content.Create - required only if a target workspace is specified in GenerateTokenRequestV2
  • Report.ReadWrite.All or Report.Read.All - required only if a report is specified in GenerateTokenRequestV2
  • Report.ReadWrite.All - required if allowEdit flag is specified for at least one report in GenerateTokenRequestV2
  • Dataset.ReadWrite.All or Dataset.Read.All
To set the permissions scope, see Register an app.
When using service principal for authentication, refer to Service Principal with Power BI document along with considerations and limitations section.

Restrictions

  • All the reports and datasets must reside in workspace V2. All the target workpaces must be workspace V2.
  • Maximum number of reports, datasets and target workspaces is 50 each.
  • Generating Embed Token with RLS may not work for AS Azure or AS OnPrem live connection reports for several minutes after a Rebind.
  • Paginated reports are not supported.

POST https://api.powerbi.com/v1.0/myorg/GenerateToken

Request Body

Name Type Description
datasets

List of datasets
identities

List of identities to use for RLS rules.
reports

List of reports
targetWorkspaces

List of workspaces Embed Token allows saving to

Responses

Name Type Description
200 OK

OK

Examples

Generate EmbedToken for a dataset and two reports. Editing is allowed for only one of the two reports
Generate EmbedToken for two datasets with RLS identities and a single report with read-only permissions. This token allows to view the report dynamically bound to two different datasets

Generate EmbedToken for a dataset and two reports. Editing is allowed for only one of the two reports

Sample Request

POST https://api.powerbi.com/v1.0/myorg/GenerateToken
Request Body
{
  "datasets": [
    {
      "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
    }
  ],
  "reports": [
    {
      "allowEdit": true,
      "id": "b2e49b01-2356-4456-bfb9-3f4c2bc4ddbd"
    },
    {
      "id": "759908bb-ead8-4a43-9645-7ffbf921c68d"
    }
  ]
}

Sample Response

Status code:
200 
{
  "token": "H4sI....AAA=",
  "tokenId": "49ae3742-54c0-4c29-af52-619ff93b5c80",
  "expiration": "2018-07-29T17:58:19Z"
}

Generate EmbedToken for two datasets with RLS identities and a single report with read-only permissions. This token allows to view the report dynamically bound to two different datasets

Sample Request

POST https://api.powerbi.com/v1.0/myorg/GenerateToken
Request Body
{
  "datasets": [
    {
      "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
    },
    {
      "id": "e75afc47-1150-45e0-aba7-4eb04e4876e5"
    }
  ],
  "reports": [
    {
      "id": "b2e49b01-2356-4456-bfb9-3f4c2bc4ddbd"
    }
  ],
  "identities": [
    {
      "username": "john@contoso.com",
      "roles": [
        "sales"
      ],
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    },
    {
      "username": "iris@contoso.com",
      "roles": [
        "executive"
      ],
      "datasets": [
        "e75afc47-1150-45e0-aba7-4eb04e4876e5"
      ]
    }
  ]
}

Sample Response

Status code:
200 
{
  "token": "H4sI....AAA=",
  "tokenId": "4b76f5ed-5a06-4150-8d1b-60f8e4c186f4",
  "expiration": "2028-07-29T17:58:19Z"
}

Definitions

EffectiveIdentity

Defines the user identity and roles, for more details see this article
EmbedToken

Power BI embed token
GenerateTokenRequestV2

Power BI Generate Token Request V2
GenerateTokenRequestV2Dataset

The dataset object for Generate Token Request V2.
GenerateTokenRequestV2Report

The report object for Generate Token Request V2.
GenerateTokenRequestV2TargetWorkspace

The workspace object for Generate Token Request V2.
IdentityBlob

A blob for specifying the identity. Only supported for datasets with Direct Query connection to SQL Azure

EffectiveIdentity

Defines the user identity and roles, for more details see this article

Name Type Description
customData
  • string

The value of customdata to be used for applying RLS rules. Only supported for live connections to Azure Analysis Services.
datasets
  • string[]

An array of datasets for which this identity applies
identityBlob

A blob for specifying the identity. Only supported for datasets with Direct Query connection to SQL Azure
reports
  • string[]

An array of reports for which this identity applies, Only supported for paginated reports
roles
  • string[]

An array of RLS roles reflected by a token when applying RLS rules (identity can contain up to 50 roles, role can be composed of any character besides ',' and must be up to 50 characters)
username
  • string

The effective username reflected by a token for applying RLS rules (For OnPrem model, username can be composed of alpha-numerical characters or any of the following characters '.', '-', '_', '!', '#', '^', '~', '\', '@', also username cannot contain spaces. For Cloud model, username can be composed of all ASCII characters. username must be up to 256 characters)

EmbedToken

Power BI embed token

Name Type Description
expiration
  • string

Expiration time of token. In UTC.
token
  • string

Embed token
tokenId
  • string

Unique token Id. Can be used to correlate operations that use this token with the generate operation through audit logs.

GenerateTokenRequestV2

Power BI Generate Token Request V2

Name Type Description
datasets

List of datasets
identities

List of identities to use for RLS rules.
reports

List of reports
targetWorkspaces

List of workspaces Embed Token allows saving to

GenerateTokenRequestV2Dataset

The dataset object for Generate Token Request V2.

Name Type Description
id
  • string

Dataset Id

GenerateTokenRequestV2Report

The report object for Generate Token Request V2.

Name Type Description
allowEdit
  • boolean

Indicates that the generated EmbedToken grand editing for this report
id
  • string

Report Id

GenerateTokenRequestV2TargetWorkspace

The workspace object for Generate Token Request V2.

Name Type Description
id
  • string

Workspace Id

IdentityBlob

A blob for specifying the identity. Only supported for datasets with Direct Query connection to SQL Azure

Name Type Description
value
  • string

OAuth2 access token for SQL Azure