Embed Token - Reports GenerateTokenInGroup

Generates an embed token to view or edit the specified report from the specified workspace.

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

When using a service principal for authentication, refer to Embed Power BI content with service principal and Considerations and limitations.

Required scope

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

  • Report.ReadWrite.All or Report.Read.All
  • Dataset.ReadWrite.All or Dataset.Read.All
  • Content.Create, required if the allowSaveAs flag is specified in GenerateTokenRequest

Limitations

For Azure Analysis Services or Analysis Services on-premises live connection reports, generating an embed token with row-level security may not work for several minutes after a Rebind Report.

POST https://api.powerbi.com/v1.0/myorg/groups/{groupId}/reports/{reportId}/GenerateToken

URI Parameters

Name In Required Type Description
groupId
path True
  • string
uuid

The workspace ID

reportId
path True
  • string
uuid

The report ID

Request Body

Name Type Description
accessLevel

The required access level for embed token generation

allowSaveAs
  • boolean

Whether an embedded report can be saved as a new report. The default value is false. Only applies when you generate an embed token for report embedding.

datasetId
  • string

The dataset ID used for report creation. Only applies when you generate an embed token for report creation.

identities

A 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 expiration time of a token, but not to extend it. The value must be a positive integer. Zero (0) is equivalent to null and will be ignored, resulting in the default expiration time.

Responses

Name Type Description
200 OK

OK

Examples

Generate paginated report EmbedToken with EffectiveIdentity
Generate report EmbedToken for editing, using EffectiveIdentity
Generate report EmbedToken for view and allow saving as new report
Generate report EmbedToken using EffectiveIdentity with IdentityBlob
Generate report EmbedToken using EffectiveIdentity with multiple roles
Generate report EmbedToken with EffectiveIdentity
Generate report EmbedToken with EffectiveIdentity (Using CustomData for Azure AS)

Generate paginated report EmbedToken with EffectiveIdentity

Sample Request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken
{
  "accessLevel": "View",
  "identities": [
    {
      "username": "John Smith",
      "reports": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ]
}

Sample Response

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

Generate report EmbedToken for editing, using EffectiveIdentity

Sample Request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken
{
  "accessLevel": "Edit",
  "identities": [
    {
      "username": "john@contoso.com",
      "roles": [
        "sales"
      ],
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ]
}

Sample Response

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

Generate report EmbedToken for view and allow saving as new report

Sample Request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken
{
  "accessLevel": "View",
  "allowSaveAs": "true"
}

Sample Response

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

Generate report EmbedToken using EffectiveIdentity with IdentityBlob

Sample Request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken
{
  "accessLevel": "View",
  "identities": [
    {
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ],
      "identityBlob": {
        "value": "eyJ0eX....AAA="
      }
    }
  ]
}

Sample Response

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

Generate report EmbedToken using EffectiveIdentity with multiple roles

Sample Request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken
{
  "accessLevel": "View",
  "identities": [
    {
      "username": "john@contoso.com",
      "roles": [
        "sales",
        "marketing"
      ],
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ]
}

Sample Response

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

Generate report EmbedToken with EffectiveIdentity

Sample Request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken
{
  "accessLevel": "View",
  "identities": [
    {
      "username": "john@contoso.com",
      "roles": [
        "sales"
      ],
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ]
}

Sample Response

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

Generate report EmbedToken with EffectiveIdentity (Using CustomData for Azure AS)

Sample Request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken
{
  "accessLevel": "View",
  "identities": [
    {
      "username": "john@contoso.com",
      "customData": "john_contoso.com",
      "roles": [
        "sales"
      ],
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ]
}

Sample Response

{
  "token": "H4sI....AAA=",
  "tokenId": "49ae3742-54c0-4c29-af52-619ff93b5c80",
  "expiration": "2018-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

GenerateTokenRequest

Power BI Generate Token Request

IdentityBlob

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

TokenAccessLevel

The required access level for embed token generation

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.

GenerateTokenRequest

Power BI Generate Token Request

Name Type Description
accessLevel

The required access level for embed token generation

allowSaveAs
  • boolean

Whether an embedded report can be saved as a new report. The default value is false. Only applies when you generate an embed token for report embedding.

datasetId
  • string

The dataset ID used for report creation. Only applies when you generate an embed token for report creation.

identities

A 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 expiration time of a token, but not to extend it. The value must be a positive integer. Zero (0) is equivalent to null and will be ignored, resulting in the default expiration time.

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

TokenAccessLevel

The required access level for embed token generation

Name Type Description
Create
  • string

Indicates that the generated embed token grants create permission. Only applies when you generate an embed token for report creation.

Edit
  • string

Indicates that the generated embed token grants view and edit permissions. Only applies when you generate an embed token for report embedding.

View
  • string

Indicates that the generated embed token grants view-only permission