Embed Token - Generate Token

Generates an embed token for multiple reports, datasets, and target workspaces.

  • Reports and datasets don't have to be related.
  • You can bind a report to a dataset during embedding.
  • You can only create a report in workspaces specified by the targetWorkspaces parameter.

Important

This API is only relevant to the embed for your customers scenario. To learn more about using this API, see Considerations when generating an embed token.

Permissions

Required scope

All of the following, unless a requirement doesn't apply:

  • Content.Create, required if a target workspace is specified in GenerateTokenRequestV2.
  • Report.ReadWrite.All or Report.Read.All, required if a report is specified in GenerateTokenRequestV2.
  • Report.ReadWrite.All, required if the allowEdit flag is specified for at least one report in GenerateTokenRequestV2.
  • Dataset.ReadWrite.All or Dataset.Read.All

Limitations

  • You can only create a report in workspaces specified by the targetWorkspaces parameter.
  • All reports and datasets must reside in a V2 workspace.
  • All target workspaces must be V2 workspaces.
  • Maximum 50 reports.
  • Maximum 50 datasets.
  • Maximum 50 target workspaces.
  • For Azure Analysis Services or Analysis Services on-premises live connection reports, generating an embed token with row-level security might not work for several minutes after a rebind.
POST https://api.powerbi.com/v1.0/myorg/GenerateToken

Request Body

Name Type Description
datasets

A list of datasets

identities

The list of identities to use for row-level security rules

lifetimeInMinutes
  • integer

The maximum lifetime of the token in minutes, starting from the time it was generated. Can be used to shorten the token's expiration time, but not to extend it. The value must be a positive integer. Zero (0) is equivalent to null, and will set the default expiration time.

reports

A list of reports

targetWorkspaces

The list of workspaces that the embed token will allow saving to

Responses

Name Type Description
200 OK

OK

Examples

Generate an Embed Token expiring in 10 minutes
Generate an EmbedToken for a Power BI report with a paginated visual. The paginated Report ID "(f904e89a-7ebe-4aa0-8647-e409063b4850)" of the paginated visual has to be included in the report IDs section.
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 an Embed Token expiring in 10 minutes

Sample Request

POST https://api.powerbi.com/v1.0/myorg/GenerateToken
{
  "datasets": [
    {
      "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
    }
  ],
  "reports": [
    {
      "id": "b2e49b01-2356-4456-bfb9-3f4c2bc4ddbd"
    }
  ],
  "identities": [
    {
      "username": "john@contoso.com",
      "roles": [
        "sales"
      ],
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ],
  "lifetimeInMinutes": 10
}

Sample Response

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

Generate an EmbedToken for a Power BI report with a paginated visual. The paginated Report ID "(f904e89a-7ebe-4aa0-8647-e409063b4850)" of the paginated visual has to be included in the report IDs section.

Sample Request

POST https://api.powerbi.com/v1.0/myorg/GenerateToken
{
  "datasets": [
    {
      "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
    }
  ],
  "reports": [
    {
      "id": "b2e49b01-2356-4456-bfb9-3f4c2bc4ddbd"
    },
    {
      "id": "f904e89a-7ebe-4aa0-8647-e409063b4850"
    }
  ]
}

Sample Response

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

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
{
  "datasets": [
    {
      "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
    }
  ],
  "reports": [
    {
      "allowEdit": true,
      "id": "b2e49b01-2356-4456-bfb9-3f4c2bc4ddbd"
    },
    {
      "id": "759908bb-ead8-4a43-9645-7ffbf921c68d"
    }
  ]
}

Sample Response

{
  "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
{
  "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

{
  "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 information, see Row-level security with Power BI Embedded.

EmbedToken

A Power BI embed token

GenerateTokenRequestV2

Power BI Generate Token Request V2

GenerateTokenRequestV2Dataset

A dataset object in GenerateTokenRequestV2

GenerateTokenRequestV2Report

A report object in GenerateTokenRequestV2

GenerateTokenRequestV2TargetWorkspace

A workspace object in GenerateTokenRequestV2

IdentityBlob

A blob for specifying an identity. Only supported for datasets with a DirectQuery connection to Azure SQL

EffectiveIdentity

Defines the user identity and roles. For more information, see Row-level security with Power BI Embedded.

Name Type Description
customData
  • string

Custom data that's used to apply row-level security rules. Only supported for live connections to Azure Analysis Services.

datasets
  • string[]

An array of datasets for which this identity applies

identityBlob

A blob that specifies an identity. Only supported for datasets with a DirectQuery connection to Azure SQL.

reports
  • string[]

An array of reports for which this identity applies. Only supported for paginated reports.

roles
  • string[]

An array of row-level security (RLS) roles within a token that applies RLS rules. An identity can contain up to 50 roles. A role can contain any character except ,, and its length must not exceed 50 characters.

username
  • string

The effective username within a token that applies row-level security rules. For an on-premises model, the username can contain alphanumeric or any of the following characters ., -, _, !, #, ^, ~, \\, @. For cloud models, the username can contain any ASCII character. For either model, the username length must not exceed 256 characters, and the username shouldn't contain spaces.

EmbedToken

A Power BI embed token

Name Type Description
expiration
  • string

The date and time (UTC) of token expiration

token
  • string

The embed token

tokenId
  • string

The unique token ID. Through audit logs, the token ID can be used to correlate operations that use the token with the generate operation.

GenerateTokenRequestV2

Power BI Generate Token Request V2

Name Type Description
datasets

A list of datasets

identities

The list of identities to use for row-level security rules

lifetimeInMinutes
  • integer

The maximum lifetime of the token in minutes, starting from the time it was generated. Can be used to shorten the token's expiration time, but not to extend it. The value must be a positive integer. Zero (0) is equivalent to null, and will set the default expiration time.

reports

A list of reports

targetWorkspaces

The list of workspaces that the embed token will allow saving to

GenerateTokenRequestV2Dataset

A dataset object in GenerateTokenRequestV2

Name Type Description
id
  • string

The dataset ID

GenerateTokenRequestV2Report

A report object in GenerateTokenRequestV2

Name Type Description
allowEdit
  • boolean

Whether the generated embed token supports report editing

id
  • string

The report ID

GenerateTokenRequestV2TargetWorkspace

A workspace object in GenerateTokenRequestV2

Name Type Description
id
  • string

The workspace ID

IdentityBlob

A blob for specifying an identity. Only supported for datasets with a DirectQuery connection to Azure SQL

Name Type Description
value
  • string

An OAuth 2.0 access token for Azure SQL