Embed Token - Reports GenerateTokenInGroup

Reference

Service:: Power BI REST APIs

API Version:: v1.0

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

Tip

To create embed tokens, it's recommended to use the latest API, Generate Token. Generate token supports additional functions, such as creating a token for multiple items.

Important

This API call 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.
This API call can be called by a service principal profile. For more information see: Service principal profiles in Power BI Embedded.

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	TokenAccessLevel	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	EffectiveIdentity[]	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	EmbedToken	OK

Examples

Generate a paginated report embed token using an effective identity example

Generate a report embed token for editing example. The embed token uses an effective identity.

Generate a report embed token for viewing a report and saving to a new report example

Generate a report embed token using an effective identity example

Generate a report embed token using an effective identity with an identity blob example

Generate a report embed token using an effective identity with custom data for Azure Analysis Services example

Generate a report embed token using an effective identity with multiple roles example

Generate a paginated report embed token using an effective identity example

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken

Request Body

{
  "accessLevel": "View",
  "identities": [
    {
      "username": "John Smith",
      "reports": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ]
}

Sample response

Status code:: 200

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

Generate a report embed token for editing example. The embed token uses an effective identity.

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken

Request Body

{
  "accessLevel": "Edit",
  "identities": [
    {
      "username": "john@contoso.com",
      "roles": [
        "sales"
      ],
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ]
}

Sample response

Status code:: 200

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

Generate a report embed token for viewing a report and saving to a new report example

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken

Request Body

{
  "accessLevel": "View",
  "allowSaveAs": "true"
}

Sample response

Status code:: 200

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

Generate a report embed token using an effective identity example

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken

Request Body

{
  "accessLevel": "View",
  "identities": [
    {
      "username": "john@contoso.com",
      "roles": [
        "sales"
      ],
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ]
}

Sample response

Status code:: 200

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

Generate a report embed token using an effective identity with an identity blob example

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken

Request Body

{
  "accessLevel": "View",
  "identities": [
    {
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ],
      "identityBlob": {
        "value": "eyJ0eX....AAA="
      }
    }
  ]
}

Sample response

Status code:: 200

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

Generate a report embed token using an effective identity with custom data for Azure Analysis Services example

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken

Request Body

{
  "accessLevel": "View",
  "identities": [
    {
      "username": "john@contoso.com",
      "customData": "john_contoso.com",
      "roles": [
        "sales"
      ],
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ]
}

Sample response

Status code:: 200

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

Generate a report embed token using an effective identity with multiple roles example

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/reports/5b218778-e7a5-4d73-8187-f10824047715/GenerateToken

Request Body

{
  "accessLevel": "View",
  "identities": [
    {
      "username": "john@contoso.com",
      "roles": [
        "sales",
        "marketing"
      ],
      "datasets": [
        "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
      ]
    }
  ]
}

Sample response

Status code:: 200

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

Definitions

Name	Description
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
auditableContext	string	The EffectiveIdentity auditable context. If this parameter is provided and isn't empty, it will enable auditing of the EffectiveIdentity and its value will be set to the username in the audit record. Otherwise, the EffectiveIdentity context will be omitted from the GenerateToken audit record.
customData	string	Custom data that's used to apply row-level security rules. Supported for live connection to Azure Analysis Services models and cloud models only.
datasets	string[]	An array of datasets for which this identity applies
identityBlob	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	TokenAccessLevel	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	EffectiveIdentity[]	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

Share via

Embed Token - Reports GenerateTokenInGroup

Permissions

Required Scope

Limitations

URI Parameters

Request Body

Responses

Examples

Generate a paginated report embed token using an effective identity example

Sample request

Sample response

Generate a report embed token for editing example. The embed token uses an effective identity.

Sample request

Sample response

Generate a report embed token for viewing a report and saving to a new report example

Sample request

Sample response

Generate a report embed token using an effective identity example

Sample request

Sample response

Generate a report embed token using an effective identity with an identity blob example

Sample request

Sample response

Generate a report embed token using an effective identity with custom data for Azure Analysis Services example

Sample request

Sample response

Generate a report embed token using an effective identity with multiple roles example

Sample request

Sample response

Definitions

EffectiveIdentity

EmbedToken

GenerateTokenRequest

IdentityBlob

TokenAccessLevel

Additional resources