Admin - InformationProtection SetLabelsAsAdmin

Set sensitivity labels on Power BI items (such as reports or dashboards) by item ID.

To set a sensitivity label using this API, the admin user or the delegated user (if provided) must have the label included in their label policy. For a usage example, see Set or remove sensitivity labels.

Permissions

  • The user must have administrator rights (such as Office 365 Global Administrator or Power BI Service Administrator).
  • The admin user and the delegated user (if provided) must have sufficient usage rights to set labels.

Required Scope

Tenant.ReadWrite.All

Limitations

  • Maximum 25 requests per hour.
  • Each request can update up to 2,000 Power BI items.

POST https://api.powerbi.com/v1.0/myorg/admin/informationprotection/setLabels

Request Body

Name Required Type Description
artifacts True

A composite of Power BI item IDs for each item type

labelId True
  • string

The label ID, which must be in the user's label policy.

assignmentMethod

Specifies whether the assigned label was set by an automated process or manually.

delegatedUser

Delegated user details. A delegated user is a user within an organization whose admin sets a label on behalf of the user. Although the admin sets the label, the delegated user is marked as the label issuer.

Responses

Name Type Description
200 OK

OK

Examples

Example

Sample Request

POST https://api.powerbi.com/v1.0/myorg/admin/informationprotection/setLabels
{
  "artifacts": {
    "dashboards": [
      {
        "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542a"
      },
      {
        "id": "476fcafe-b514-495d-b13f-ca9a4f0b1d8b"
      }
    ],
    "reports": [
      {
        "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542c"
      }
    ],
    "datasets": [
      {
        "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542e"
      },
      {
        "id": "myDatabaseName"
      }
    ],
    "dataflows": [
      {
        "id": "476fcafe-b514-495d-b13f-ca9a4f0b1d8g"
      }
    ]
  },
  "labelId": "fe472f5e-636e-4c10-a1c6-7e9edc0b542p",
  "assignmentMethod": "Standard",
  "delegatedUser": {
    "emailAddress": "john@contoso.com"
  }
}

Sample Response

{
  "dashboards": [
    {
      "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542a",
      "status": "NotFound"
    },
    {
      "id": "476fcafe-b514-495d-b13f-ca9a4f0b1d8b",
      "status": "Failed"
    }
  ],
  "reports": [
    {
      "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542c",
      "status": "Succeeded"
    }
  ],
  "datasets": [
    {
      "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542e",
      "status": "InsufficientUsageRights"
    },
    {
      "id": "myDatabaseName",
      "status": "FailedToGetUsageRights"
    }
  ],
  "dataflows": [
    {
      "id": "476fcafe-b514-495d-b13f-ca9a4f0b1d8g",
      "status": "Succeeded"
    }
  ]
}

Definitions

ArtifactId

The unique ID of a Power BI item in UUID format. Dashboard, report, and dataflow IDs are in UUID format, and dataset IDs can be in UUID or string format.

ArtifactStringId

The unique ID of a Power BI item in string or UUID format. Dashboard, report, and dataflow IDs are in UUID format, and dataset IDs can be in UUID or string format.

assignmentMethod

Specifies whether the assigned label was set by an automated process or manually.

ChangeLabelStatus

The unique ID and information protection label change status of a Power BI item

DelegatedUser

Delegated user details. The user must be an existing user in Power BI and Azure AAD, and must have signed in to Power BI during the last three months.

InformationProtectionArtifactsChangeLabel

A composite of Power BI item IDs for each item type. The IDs specify which Power BI items require an information protection label update.

InformationProtectionChangeLabelDetails

A composite of label information required to update an information protection label

InformationProtectionChangeLabelResponse

A composite of the ID and information protection label change status for one or more Power BI items organized by type

status

The status of an information protection label change operation

ArtifactId

The unique ID of a Power BI item in UUID format. Dashboard, report, and dataflow IDs are in UUID format, and dataset IDs can be in UUID or string format.

Name Type Description
id
  • string

An ID in UUID format

ArtifactStringId

The unique ID of a Power BI item in string or UUID format. Dashboard, report, and dataflow IDs are in UUID format, and dataset IDs can be in UUID or string format.

Name Type Description
id
  • string

An ID in string or UUID format

assignmentMethod

Specifies whether the assigned label was set by an automated process or manually.

Name Type Description
Priviledged
  • string

The label was set manually

Standard
  • string

The label was set by an automated process (default value)

ChangeLabelStatus

The unique ID and information protection label change status of a Power BI item

Name Type Description
id
  • string

The unique ID of a Power BI item. The ID is in UUID format for dashboards, reports, and dataflows; and in UUID or string format for datasets.

status

The status of an information protection label change operation

DelegatedUser

Delegated user details. The user must be an existing user in Power BI and Azure AAD, and must have signed in to Power BI during the last three months.

Name Type Description
emailAddress
  • string

The email address of the delegated user

InformationProtectionArtifactsChangeLabel

A composite of Power BI item IDs for each item type. The IDs specify which Power BI items require an information protection label update.

Name Type Description
dashboards

A list of unique dashboard IDs

dataflows

A list of unique dataflow IDs

datasets

A list of unique dataset IDs

reports

A list of unique report IDs

InformationProtectionChangeLabelDetails

A composite of label information required to update an information protection label

Name Type Description
artifacts

A composite of Power BI item IDs for each item type

assignmentMethod

Specifies whether the assigned label was set by an automated process or manually.

delegatedUser

Delegated user details. A delegated user is a user within an organization whose admin sets a label on behalf of the user. Although the admin sets the label, the delegated user is marked as the label issuer.

labelId
  • string

The label ID, which must be in the user's label policy.

InformationProtectionChangeLabelResponse

A composite of the ID and information protection label change status for one or more Power BI items organized by type

Name Type Description
dashboards

A list containing the unique ID and information protection label change status of one or more dashboards

dataflows

A list containing the unique ID and information protection label change status of one or more dataflows

datasets

A list containing the unique ID and information protection label change status of one or more datasets

reports

A list containing the unique ID and information protection label change status of one or more reports

status

The status of an information protection label change operation

Name Type Description
Failed
  • string

Failed to set a new label. Please retry.

FailedToGetUsageRights
  • string

Failed to set a new label. The Power BI item has a sensitivity label with protection settings, and Power BI was unable to verify that the user has sufficient usage rights to change the label.

InsufficientUsageRights
  • string

Failed to set a new label. The Power BI item has a sensitivity label with protection settings, and the admin user (and the delegated user, if provided) doesn't have sufficient usage rights to change the label.

NotFound
  • string

The Power BI item ID or label wasn't found

Succeeded
  • string

The Power BI item label was changed