docs: Microsoft Power BI OAuth provider

app/en/references/auth-providers/microsoft-powerbi/page.mdx

@@ -0,0 +1,255 @@
+---
+title: Microsoft Power BI
+description: Authorize tools and agents with the Power BI Service on behalf of a user
+---
+
+import { Tabs, Callout, Steps } from "nextra/components";
+
+# Microsoft Power BI
+
+<Callout type="info">
+  Microsoft Power BI is a **dedicated** auth provider, separate from the
+  general-purpose [Microsoft](/references/auth-providers/microsoft) provider. To
+  use it, create a custom auth provider of type **Microsoft Power BI** with your
+  own Microsoft Entra (Azure AD) OAuth 2.0 credentials as described below.
+</Callout>
+
+The Microsoft Power BI auth provider enables tools and agents to call the [Power BI REST API](https://learn.microsoft.com/en-us/rest/api/power-bi/) on behalf of a user.
+
+Power BI has its own provider so that its permissions stay separate from the Microsoft Graph permissions used by the general-purpose Microsoft provider. Mixing the two breaks authorization — if you want to know why, see [Advanced: token audiences and troubleshooting](#advanced-token-audiences-and-troubleshooting) at the end of this page.
+
+### What's documented here
+
+This page describes how to use and configure Microsoft Power BI auth with Arcade.
+
+This auth provider is used by:
+
+- The Arcade **Power BI MCP Server**, which discovers workspaces, datasets, and reports; inspects and queries semantic models with DAX; and manages dataset refreshes
+- Your [app code](#using-microsoft-power-bi-auth-in-app-code) that needs to call Power BI REST APIs
+- Or, your [custom tools](#using-microsoft-power-bi-auth-in-custom-tools) that need to call Power BI REST APIs
+
+## Configuring Microsoft Power BI auth
+
+<Callout type="info">
+  When using your own app credentials, make sure you configure your project to
+  use a [custom user
+  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
+  Without this, your end-users will not be able to use your app or agent in
+  production.
+</Callout>
+
+In a production environment, you will most likely want to use your own Microsoft app credentials. This way, your users will see your application's name requesting permission.
+
+Before showing how to configure your Power BI app credentials, let's go through the steps to create a Microsoft Entra app.
+
+### Create a Microsoft Entra app
+
+- Follow Microsoft's guide to [registering an app with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
+- Set the redirect URL to the redirect URL generated by Arcade (see below).
+- Under **API permissions**, add the **Power BI Service** delegated permissions listed in the [section below](#power-bi-service-scopes). Then **Grant admin consent** for the permissions.
+- Copy the client ID and client secret to use below.
+
+<Callout type="warning">
+  Add **only** the Power BI Service permissions listed below to this app — do
+  not add permissions from other Microsoft APIs, such as Microsoft Graph's
+  `User.Read`. Mixing permissions from different Microsoft APIs on this app
+  causes sign-in failures (see the [Advanced
+  section](#advanced-token-audiences-and-troubleshooting)).
+</Callout>
+
+### Power BI Service scopes
+
+Add the following **Power BI Service** delegated permissions to your Entra app. These cover the permissions used by the Arcade Power BI MCP Server:
+
+| Permission              | Used for                                          |
+| ----------------------- | ------------------------------------------------- |
+| `Workspace.Read.All`    | Listing workspaces and reading the signed-in user |
+| `Dataset.Read.All`      | Listing datasets, reading schemas, running DAX    |
+| `Dataset.ReadWrite.All` | Triggering dataset refreshes                      |
+| `Report.Read.All`       | Listing and reading reports                       |
+
+In addition, add the standard OpenID Connect permissions `openid`, `profile`, and `offline_access` (the last is required to issue refresh tokens).
+
+To enable schema inspection and DAX queries, an administrator must also turn on the **Dataset Execute Queries REST API** tenant setting (a.k.a. _Semantic Model Execute Queries_) in the Power BI admin portal.
+
+Next, add the Power BI app to Arcade.
+
+## Configuring your own Microsoft Power BI Auth Provider in Arcade
+
+<Tabs items={["Dashboard GUI"]}>
+<Tabs.Tab>
+
+### Configure Microsoft Power BI Auth Using the Arcade Dashboard GUI
+
+<Steps>
+
+#### Access the Arcade Dashboard
+
+To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment.
+
+#### Navigate to the OAuth Providers page
+
+- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**.
+- Click **Add OAuth Provider** in the top right corner.
+- Select the **Included Providers** tab at the top.
+- In the **Provider** dropdown, select **Microsoft Power BI**.
+
+#### Enter the provider details
+
+- Choose a unique **ID** for your provider (e.g. "my-powerbi-provider").
+- Optionally enter a **Description**.
+- Enter the **Client ID** and **Client Secret** from your Microsoft Entra app.
+- **Leave the Scopes field empty.** Each tool requests the scopes it needs when it runs, so the provider only carries your credentials (see [why](#advanced-token-audiences-and-troubleshooting)).
+- Note the **Redirect URL** generated by Arcade. This must be set as your Microsoft Entra app's redirect URL.
+
+#### Create the provider
+
+Hit the **Create** button and the provider will be ready to be used.
+
+</Steps>
+
+When you use tools that require Microsoft Power BI auth using your Arcade account credentials, Arcade will automatically use this provider. If you have multiple Microsoft Power BI providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information.
+
+</Tabs.Tab>
+</Tabs>
+
+## Using Microsoft Power BI auth in app code
+
+Use the Microsoft Power BI auth provider in your own agents and AI apps to get a user token for the Power BI REST API. See [authorizing agents with Arcade](/get-started/about-arcade) to understand how this works.
+
+Use `client.auth.start()` with the `microsoft-powerbi` provider to get a user token for Power BI APIs:
+
+<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
+<Tabs.Tab>
+
+```python {8-16}
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+user_id = "{arcade_user_id}"
+
+# Start the authorization process
+auth_response = client.auth.start(
+    user_id=user_id,
+    provider="microsoft-powerbi",
+    scopes=[
+        "https://analysis.windows.net/powerbi/api/Workspace.Read.All",
+        "https://analysis.windows.net/powerbi/api/Dataset.Read.All",
+    ],
+)
+
+if auth_response.status != "completed":
+    print("Please complete the authorization challenge in your browser:")
+    print(auth_response.url)
+
+# Wait for the authorization to complete
+auth_response = client.auth.wait_for_completion(auth_response)
+
+token = auth_response.context.token
+# TODO: Do something interesting with the token...
+```
+
+</Tabs.Tab>
+
+<Tabs.Tab>
+
+```javascript {8-13}
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade();
+
+const userId = "{arcade_user_id}";
+
+// Start the authorization process
+let authResponse = await client.auth.start(userId, "microsoft-powerbi", {
+  scopes: [
+    "https://analysis.windows.net/powerbi/api/Workspace.Read.All",
+    "https://analysis.windows.net/powerbi/api/Dataset.Read.All",
+  ],
+});
+
+if (authResponse.status !== "completed") {
+  console.log("Please complete the authorization challenge in your browser:");
+  console.log(authResponse.url);
+}
+
+// Wait for the authorization to complete
+authResponse = await client.auth.waitForCompletion(authResponse);
+
+const token = authResponse.context.token;
+// TODO: Do something interesting with the token...
+```
+
+</Tabs.Tab>
+
+</Tabs>
+
+## Using Microsoft Power BI auth in custom tools
+
+You can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with the Power BI REST API.
+
+Power BI is a Microsoft provider with its own `provider_id`, so mark a tool as requiring it by subclassing the `Microsoft` auth class and overriding `provider_id` to `microsoft-powerbi`. The `context.authorization.token` field will be automatically populated with the user's Power BI token:
+
+```python {8-11,15-19,26}
+from typing import Annotated
+
+import httpx
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import Microsoft
+
+
+class MicrosoftPowerBI(Microsoft):
+    """Microsoft OAuth bound to the dedicated `microsoft-powerbi` provider."""
+
+    provider_id: str = "microsoft-powerbi"
+
+
+@tool(
+    requires_auth=MicrosoftPowerBI(
+        scopes=["https://analysis.windows.net/powerbi/api/Dataset.Read.All"],
+    )
+)
+async def list_datasets(
+    context: ToolContext,
+    group_id: Annotated[str, "The ID of the workspace to list datasets from"],
+) -> Annotated[dict, "The datasets in the workspace"]:
+    """List the datasets in a Power BI workspace."""
+    url = f"https://api.powerbi.com/v1.0/myorg/groups/{group_id}/datasets"
+    headers = {"Authorization": f"Bearer {context.authorization.token}"}
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url=url, headers=headers)
+        response.raise_for_status()
+        return response.json()
+```
+
+## Advanced: token audiences and troubleshooting
+
+<Callout type="warning">
+  **For advanced users.** You do not need this section to complete the setup
+  above. Read it if you want to understand why Power BI needs a dedicated
+  provider, or if you are troubleshooting an authorization error such as
+  **AADSTS70011**.
+</Callout>
+
+### Why Power BI needs its own provider
+
+The Power BI provider authorizes against the **Power BI Service** resource (`https://analysis.windows.net/powerbi/api`). It reuses Microsoft's Entra ID endpoints, but on its own connection, separate from the general-purpose [Microsoft](/references/auth-providers/microsoft) provider.
+
+A Microsoft Entra access token is issued for a single resource (its _audience_). Power BI Service and Microsoft Graph are different resources, so a single authorize request cannot mix scopes from both: Entra rejects the sign-in with **AADSTS70011** (`The provided value for the input parameter scope is not valid`). Keeping Power BI on a dedicated provider guarantees every authorize request on that connection carries Power BI Service scopes only.
+
+For the same reason, the Entra app behind this provider must carry Power BI Service delegated permissions and nothing else. Do not add a Microsoft Graph permission (e.g. `User.Read`) or a Microsoft Fabric permission (`api.fabric.microsoft.com`) — any non–Power BI scope mixes token audiences on the Power BI connection and triggers **AADSTS70011** at authorize time.
+
+### Why the provider's Scopes field stays empty
+
+Individual tools request only the specific Power BI scope each endpoint needs at call time, so the Arcade provider itself carries only the client ID and secret. Entering scopes on the provider can send Entra a mixed or invalid scope set in one authorize request and trigger **AADSTS70011**.
+
+Write capability is governed entirely by the user's OAuth scopes: a user without a `*.ReadWrite.All` permission receives a `403` from the API on a write call.
+
+### Troubleshooting
+
+- **AADSTS70011 at authorize time.** The scope set in the authorize request mixes resources or is malformed. Check that the Entra app carries only Power BI Service permissions and that the provider's Scopes field is empty.
+- **Errors after changing the Entra app's permissions.** If you added or removed a permission on the Entra app (including removing a stray Graph or Fabric permission), delete and recreate the user's connection in Arcade so a fresh, single-resource token is minted.
+- **`403` on a write call.** The user's token is missing the corresponding `*.ReadWrite.All` scope. Re-authorize with the required scope.

app/en/references/auth-providers/page.mdx

@@ -99,6 +99,13 @@ For more information on how to customize your auth provider, select an auth prov
     link="/references/auth-providers/microsoft"
     category="Auth"
   />
+  <ToolCard
+    name="Microsoft Power BI"
+    image="msft"
+    summary="Authorize tools and agents with the Power BI Service"
+    link="/references/auth-providers/microsoft-powerbi"
+    category="Auth"
+  />
   <ToolCard
     name="Notion"
     image="notion"

public/llms.txt

@@ -1,4 +1,4 @@
-<!-- git-sha: 4b7cddb20669603a8aa983449f9d5f49ad826931 generation-date: 2026-07-02T19:40:13.157Z -->
+<!-- git-sha: 290d3bd19c3b25de5c588e6fb26edda0c1d1e49f generation-date: 2026-07-08T21:47:19.271Z -->
 
 # Arcade
 
@@ -39,6 +39,7 @@ Arcade delivers three capabilities. Enforce (Agent Authorization): deploy agents
 - [LinkedIn](https://docs.arcade.dev/en/references/auth-providers/linkedin): This documentation page provides guidance on configuring and using the LinkedIn authentication provider within Arcade, enabling applications and custom tools to access LinkedIn APIs on behalf of users. It outlines the necessary steps to create a LinkedIn app, set up app credentials, and
 - [Mailchimp](https://docs.arcade.dev/en/references/auth-providers/mailchimp): This documentation page provides guidance on configuring the Mailchimp authentication provider for use with Arcade, enabling users to access Mailchimp Marketing APIs through OAuth 2.0. It includes steps for creating a Mailchimp app, registering it, and integrating it with Arcade
 - [Microsoft](https://docs.arcade.dev/en/references/auth-providers/microsoft): This documentation page provides guidance on how to create and configure a custom Microsoft Auth Provider for use with Arcade, enabling applications and tools to access the Microsoft Graph API on behalf of users. It outlines the steps for registering a Microsoft app, setting necessary permissions,
+- [Microsoft Power BI](https://docs.arcade.dev/en/references/auth-providers/microsoft-powerbi): Documentation page
 - [Middleware](https://docs.arcade.dev/en/references/mcp/python/middleware): This documentation page provides an overview of middleware in the Arcade MCP Python framework, detailing how to intercept and modify requests and responses during processing. It introduces the base `Middleware` class for creating custom middleware, explains the `MiddlewareContext` for managing message data
 - [Miro](https://docs.arcade.dev/en/references/auth-providers/miro): This documentation page provides guidance on configuring the Miro authentication provider using OAuth 2.0, enabling users to integrate Miro APIs into their applications or tools. It outlines the steps for creating a Miro app, obtaining necessary credentials, and setting up
 - [Notion](https://docs.arcade.dev/en/references/auth-providers/notion): This documentation page provides guidance on configuring and using the Notion authentication provider with Arcade, enabling users to call Notion APIs on behalf of their users. It outlines the steps to create a Notion app, configure OAuth settings in the Arcade dashboard, and