{
  "schema": "aaes/capability-pack/1",
  "provider": "powerbi",
  "version": "1.0.0",
  "description": "Microsoft Power BI REST API on a customer workspace: read datasets, query them with DAX and read refresh history, trigger dataset refresh, delete datasets and reports, and grant workspace access.",
  "notes": "The endpoint host api.powerbi.com is a REAL shared service host — Microsoft's global Power BI API endpoint that serves every tenant — not a placeholder: do not substitute it, and do not treat its presence in the egress allowlist as an unsubstituted-pack marker. Tenant and data scoping come from the Microsoft Entra ID access token and the group (workspace) id in the path, not from the host.\n\nGROUP_ID, DATASET_ID and REPORT_ID in the paths are placeholders the deployment binds to concrete workspace and artifact ids before enabling; the /v1.0/myorg prefix is Power BI's documented tenant-relative root, and the registered capabilities address workspace-scoped operations only (My Workspace variants of the same operations are not registered).\n\nApproval classification: dataset refresh is registered with the deploy action at the minimum R3 tier rather than as an ordinary execution — a refresh rewrites the data every report and dashboard built on the dataset serves to its consumers, which is deploy-equivalent; deploy is one of the designated actions requiring human approval. Adding a principal to a workspace is registered as share at the minimum R3 tier: it grants a user, group or service principal a workspace role up to Admin, and the grant is effective until a separate removal call — an access grant requires a separate removal call.\n\nDocumented exclusions — this pack does not register: the Admin APIs (tenant-wide as-admin scans and metadata export — organization-wide surveillance scope, a separate governance review); Post Dataset User and Put Dataset User (direct dataset-level permission grants — share-class, pending review); Take Over In Group (transfers dataset ownership to the calling user — transfer-class); Bind To Gateway In Group, Update Datasources In Group and Set All Dataset Connections In Group (gateway binding and data-source credential operations — credential-adjacent writes requiring their own review); the push/streaming dataset row endpoints (PostRows and friends — direct row writes into datasets); report clone, export and import; dataflow refresh and transactions; and GenerateToken (embed-token issuance — a credential-issuance operation, not a business capability).\n\nThese operations are excluded. The Execute Queries capability is a POST-with-query-body endpoint used read-only: its body carries a DAX query and it changes nothing — see the capability's own note. Capacity behaviors documented by Microsoft are honest limits, not restrictions this pack imposes: shared capacities accept at most eight refreshes per dataset per day, and an enhanced refresh whose commitMode is partialBatch can leave the model partially loaded after a failure — Microsoft's own documentation advises transactional mode to preserve previous data.\n\nBrokered execution defaults to digest mode: it records a response digest and discards the body. These schema-1 packs do not configure result delivery. Returning HTTP content needs a reviewed deployment registration with inline_bounded results, content-type and size limits, and any required data-owner acknowledgement. The bounded HTTP result path does not support SQL, email or telephony.",
  "credential": {
    "secret_ref_id": "secret-ref-powerbi-bearer-token",
    "custody": "customer_vault",
    "inject": "header",
    "inject_name": "Authorization",
    "note": "A Microsoft Entra ID (Azure AD) access token for the Power BI API, held in the client's own secret manager. The stored material must be the complete Authorization header value: the scheme 'Bearer', one separating space, then the access token. Token issuance is external: the deployment's custody job obtains tokens from the Microsoft identity platform token endpoint (login.microsoftonline.com/{tenant}/oauth2/v2.0/token) using a confidential client — a service principal authenticating with client credentials and requesting the single scope 'https://analysis.windows.net/powerbi/api/.default' — and writes the resulting token under this reference before expiry.\n\nService-principal authorization: for service principals Microsoft recommends assigning NO Power BI API permission scopes on the app registration — the documented scopes (Dataset.ReadWrite.All, Workspace.ReadWrite.All and similar) are DELEGATED permissions for signed-in-user flows and are never used by a client-credentials service principal, so this pack does not prescribe them as the SP's governing permissions. The service principal's real authorization is (1) the tenant setting 'Allow service principals to use Power BI APIs', which the tenant administrator must enable (optionally scoped to a security group containing the SP), and (2) a workspace role — Member or Admin for the write operations — on each workspace it governs; workspace assignment is the real blast-radius control.\n\nExpiry and revocation: access tokens are short-lived (about an hour) and an expired value fails closed with a 401; the custody job must refresh proactively — the injector injects the stored value verbatim and performs no token lifecycle itself. Note carefully, distinguishing issuance from authorization: disabling the app registration stops NEW token issuance, but removing the service principal from a workspace does NOT block issuance — tokens keep being minted while the app registration lives, and workspace removal only means a (still bearer-valid) token's calls against that workspace fail authorization.\n\nAlready-issued tokens are never invalidated by either step and remain usable until they expire, so the token lifetime is the effective revocation window.\n\nLeast privilege: with no API scopes on the app registration, least privilege is exercised through workspace roles — add the service principal to only the workspaces this integration governs, with the minimum role that covers the enabled capabilities, and restrict the tenant setting's allowed security group to the group holding this SP.\n\nExecutor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack."
  },
  "capabilities": [
    {
      "capability_id": "powerbi.datasets.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "api.powerbi.com"
      ],
      "endpoint": "https://api.powerbi.com/v1.0/myorg/groups/GROUP_ID/datasets",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-powerbi-bearer-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "powerbi-workspace",
      "description": "List the datasets in one workspace (Get Datasets In Group); this pack registers the collection read only — Get Dataset In Group and the datasources/parameters sub-reads are not registered. Microsoft's documentation notes that a caller with only Read permission receives a limited subset of dataset properties — a documented API behavior, not a restriction this pack imposes.\n\nGROUP_ID is a placeholder the deployment binds before enabling; api.powerbi.com is a real shared service host and is not substituted.",
      "requires_review": true
    },
    {
      "capability_id": "powerbi.dataset.execute_queries",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "api.powerbi.com"
      ],
      "endpoint": "https://api.powerbi.com/v1.0/myorg/groups/GROUP_ID/datasets/DATASET_ID/executeQueries",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-powerbi-bearer-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "powerbi-workspace",
      "description": "Run read-only DAX queries against one dataset (Execute Queries In Group). Send one DAX query for one result table. Inspect response errors and completeness: HTTP 200 can contain limited data. Microsoft caps results at 100,000 rows or 1,000,000 values and 15 MB, whichever limit is reached first. AAES bounded HTTP results have a separate, smaller configured byte limit. The call changes no workspace data and is registered as read at R0.\n\nThe registration does not restrict DAX text. The caller can query any content accessible in the dataset; classify and handle the results according to that content.\n\nThe tenant administrator must enable Dataset Execute Queries REST API under Integration settings. The caller needs both Read and Build permissions. Service principals cannot use this operation with datasets that have row-level security or SSO-enabled data sources; those datasets reject this package's service-principal credential.\n\nBind GROUP_ID and DATASET_ID before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "powerbi.dataset.refresh_history.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "api.powerbi.com"
      ],
      "endpoint": "https://api.powerbi.com/v1.0/myorg/groups/GROUP_ID/datasets/DATASET_ID/refreshes",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-powerbi-bearer-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "powerbi-workspace",
      "description": "List the refresh history of one dataset (Get Refresh History In Group): refresh ids, types, start and end times and statuses — operational metadata about past refreshes, registered as a collection read.\n\nGROUP_ID and DATASET_ID are placeholders the deployment binds before enabling; api.powerbi.com is a real shared service host and is not substituted.",
      "requires_review": true
    },
    {
      "capability_id": "powerbi.dataset.refresh",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "api.powerbi.com"
      ],
      "endpoint": "https://api.powerbi.com/v1.0/myorg/groups/GROUP_ID/datasets/DATASET_ID/refreshes",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-powerbi-bearer-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "deploy"
      ],
      "resource_id": "powerbi-workspace",
      "description": "Refresh one dataset (Refresh Dataset In Group). The refresh reads underlying sources and replaces the data served by dependent reports and dashboards. It is registered as deploy at R3 because it changes published content.\n\nAn empty body or one containing only notifyOption requests a standard refresh. Any other field requests an enhanced refresh. With commitMode=partialBatch, failure can leave the model partly loaded or a table empty; Microsoft recommends transactional to preserve previous data.\n\nShared capacities allow at most eight refreshes per day. These are provider limits, rather than controls imposed by this registration. Bind GROUP_ID and DATASET_ID before enabling.\n\nOn supported AAES-mediated execution paths, the deploy action requires approval by an authorized person; this does not prevent calls through bypass or observation-only paths.",
      "requires_review": true
    },
    {
      "capability_id": "powerbi.dataset.delete",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "api.powerbi.com"
      ],
      "endpoint": "https://api.powerbi.com/v1.0/myorg/groups/GROUP_ID/datasets/DATASET_ID",
      "method": "DELETE",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-powerbi-bearer-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "delete"
      ],
      "resource_id": "powerbi-workspace",
      "description": "Delete a dataset from the workspace (Delete Dataset In Group). Every report and dashboard tile built on the dataset loses its data connection, and recreating the dataset later is a new artifact, not an undo. Registered as delete at the minimum R3 tier; delete is one of the designated actions requiring human approval.\n\nGROUP_ID and DATASET_ID are placeholders the deployment binds before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "powerbi.report.delete",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "api.powerbi.com"
      ],
      "endpoint": "https://api.powerbi.com/v1.0/myorg/groups/GROUP_ID/reports/REPORT_ID",
      "method": "DELETE",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-powerbi-bearer-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "delete"
      ],
      "resource_id": "powerbi-workspace",
      "description": "Delete a report from the workspace (Delete Report In Group). Dashboards pinning its visuals and anyone consuming the report lose it; the documented success response is 200 with no recoverable artifact returned. Registered as delete at the minimum R3 tier; delete is one of the designated actions requiring human approval.\n\nGROUP_ID and REPORT_ID are placeholders the deployment binds before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "powerbi.group.user.add",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "api.powerbi.com"
      ],
      "endpoint": "https://api.powerbi.com/v1.0/myorg/groups/GROUP_ID/users",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-powerbi-bearer-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "share"
      ],
      "resource_id": "powerbi-workspace-users",
      "description": "Grant a principal access to a workspace (Add Group User). The body identifies the principal with identifier or emailAddress and assigns groupUserAccessRight: Viewer, Contributor, Member, or Admin. These identifying fields are personal data.\n\nThe grant covers everything in the workspace and lasts until a separate removal call. The unrestricted body permits Admin access. Enforce any viewer-only restriction in policy. Microsoft's documented permission propagation can take time; this registration imposes no timing guarantee.\n\nRegistered as share at R3. Bind GROUP_ID before enabling.",
      "requires_review": true
    }
  ],
  "resources": [
    {
      "resource_id": "powerbi-workspace",
      "kind": "api",
      "locator": "https://api.powerbi.com/v1.0/myorg/groups/GROUP_ID",
      "data_class": "internal",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    },
    {
      "resource_id": "powerbi-workspace-users",
      "kind": "api",
      "locator": "https://api.powerbi.com/v1.0/myorg/groups/GROUP_ID/users",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    }
  ],
  "review": {
    "state": "library",
    "date": "2026-09-22",
    "sources": [
      "https://learn.microsoft.com/en-us/rest/api/power-bi/datasets (retrieved 2026-09-21)",
      "https://learn.microsoft.com/en-us/rest/api/power-bi/datasets/get-datasets-in-group (retrieved 2026-09-21)",
      "https://learn.microsoft.com/en-us/rest/api/power-bi/datasets/refresh-dataset-in-group (retrieved 2026-09-21)",
      "https://learn.microsoft.com/en-us/rest/api/power-bi/reports/delete-report-in-group (retrieved 2026-09-21)",
      "https://learn.microsoft.com/en-us/rest/api/power-bi/groups/add-group-user (retrieved 2026-09-21)",
      "https://learn.microsoft.com/en-us/rest/api/power-bi/datasets/execute-queries-in-group (retrieved 2026-09-21)",
      "https://learn.microsoft.com/en-us/rest/api/power-bi/datasets/delete-dataset-in-group (retrieved 2026-09-21)",
      "https://learn.microsoft.com/en-us/rest/api/power-bi/datasets/get-refresh-history-in-group (retrieved 2026-09-21)",
      "https://learn.microsoft.com/en-us/power-bi/developer/embedded/embed-service-principal (retrieved 2026-09-21)"
    ],
    "reviewer_id": "aaes-eng"
  }
}
