@microsoft/rayfin-guide 1.36.0-alpha.1593 → 1.36.0-alpha.1601

package/assets/docs/functions/connections/add-azure-resource.md

@@ -0,0 +1,171 @@
+---
+sidebar_position: 3
+---
+
+# Add an Azure resource
+
+Connect a function to an **Azure service** — Key Vault, Cosmos DB, Blob Storage, or Event Grid — and call it **as the signed-in user**.
+
+These are Azure resources, not Fabric items, so their endpoints come from the **Azure portal** (there is no Fabric lookup). Each pattern declares the connection, reads the token with `ctx.getToken()`, and wraps it with the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper for the Azure SDK. See [Connecting to external resources](./index.md) for the shared model.
+
+## Key Vault
+
+Read secrets from Azure Key Vault using `AudienceType.KeyVault`.
+
+```bash
+cd rayfin/functions
+npm install @azure/keyvault-secrets @azure/identity
+```
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+import { SecretClient } from "@azure/keyvault-secrets";
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "getVaultSecret",
+  async (
+    ctx: RayfinContext,
+    kvUrl: string,
+    secretName: string,
+  ): Promise<string> => {
+    const credential = new ContextTokenCredential(
+      ctx.getToken(AudienceType.KeyVault),
+    );
+    const client = new SecretClient(kvUrl, credential);
+    const secret = await client.getSecret(secretName);
+    return secret.value ?? "";
+  },
+  [udf.connection({ audienceType: AudienceType.KeyVault })],
+);
+```
+
+Provide the vault URL (e.g. `https://my-vault.vault.azure.net/`).
+
+> To read secrets stored with Rayfin itself (rather than an external Key Vault), use [`ctx.getSecret()`](../secrets.md) instead — no connection required.
+
+## Cosmos DB
+
+Connect to Azure Cosmos DB using `AudienceType.CosmosDB`. Pass the credential as `aadCredentials`:
+
+```bash
+cd rayfin/functions
+npm install @azure/cosmos
+```
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+import { CosmosClient } from "@azure/cosmos";
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "readItems",
+  async (
+    ctx: RayfinContext,
+    endpoint: string,
+    databaseId: string,
+    containerId: string,
+  ): Promise<unknown[]> => {
+    const credential = new ContextTokenCredential(
+      ctx.getToken(AudienceType.CosmosDB),
+    );
+    const client = new CosmosClient({ endpoint, aadCredentials: credential });
+    const { resources } = await client
+      .database(databaseId)
+      .container(containerId)
+      .items.readAll()
+      .fetchAll();
+    return resources;
+  },
+  [udf.connection({ audienceType: AudienceType.CosmosDB })],
+);
+```
+
+Provide the account endpoint and the database / container names.
+
+## Blob Storage
+
+Connect to Azure Blob / Table / Queue storage using `AudienceType.Storage`:
+
+```bash
+cd rayfin/functions
+npm install @azure/storage-blob
+```
+
+```ts
+import { BlobServiceClient } from "@azure/storage-blob";
+
+udf.func(
+  "listBlobs",
+  async (ctx: RayfinContext, accountUrl: string): Promise<string[]> => {
+    const credential = new ContextTokenCredential(
+      ctx.getToken(AudienceType.Storage),
+    );
+    const service = new BlobServiceClient(accountUrl, credential);
+    const names: string[] = [];
+    for await (const container of service.listContainers()) {
+      names.push(container.name);
+    }
+    return names;
+  },
+  [udf.connection({ audienceType: AudienceType.Storage })],
+);
+```
+
+Provide the storage account URL (e.g. `https://<account>.blob.core.windows.net`).
+
+> `AudienceType.Storage` also covers **OneLake** files — that Fabric case is documented in [Add a Fabric resource → OneLake files](./add-fabric-resource.md#onelake-files).
+
+## Event Grid
+
+Publish events to an Azure Event Grid topic using `AudienceType.EventGrid`. The topic endpoint is in the Azure portal → your topic → **Overview** → _Topic Endpoint_.
+
+```bash
+cd rayfin/functions
+npm install @azure/eventgrid
+```
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+import { EventGridPublisherClient } from "@azure/eventgrid";
+
+const udf = new UserDataFunctions();
+
+const TOPIC_ENDPOINT =
+  "https://<topic>.<region>.eventgrid.azure.net/api/events";
+
+udf.func(
+  "publishEvent",
+  async (ctx: RayfinContext, subject: string): Promise<string> => {
+    const client = new EventGridPublisherClient(
+      TOPIC_ENDPOINT,
+      "EventGrid",
+      new ContextTokenCredential(ctx.getToken(AudienceType.EventGrid)),
+    );
+    await client.send([
+      {
+        eventType: "Rayfin.Function.Event",
+        subject,
+        dataVersion: "1.0",
+        data: { source: "user-data-function" },
+      },
+    ]);
+    return "published";
+  },
+  [udf.connection({ audienceType: AudienceType.EventGrid })],
+);
+```

package/assets/docs/functions/connections/add-fabric-resource.md

@@ -0,0 +1,186 @@
+---
+sidebar_position: 2
+---
+
+# Add a Fabric resource
+
+Connect a function to a **Microsoft Fabric item** — a Lakehouse, Warehouse, SQL Database, OneLake files, or an Eventhouse (KQL) — and call it **as the signed-in user**.
+
+**Before you start:** you need the item's coordinates (SQL endpoint, OneLake path, or Kusto query URI). See [Get Fabric info](./get-fabric-info.md) for how to pull them from the Fabric REST API.
+
+All the patterns below follow the same model: declare the connection, read the token with `ctx.getToken()`, use it. See [Connecting to external resources](./index.md) for the shared model and the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper referenced here.
+
+## SQL databases
+
+Covers Fabric **Lakehouse** (SQL analytics endpoint), **Warehouse**, **SQL Database**, and **Mirrored Database**, using `AudienceType.Sql`. The same `AudienceType.Sql` connection also works for **Azure SQL Database** — use the Azure SQL server FQDN as `server` and the database name as `database` (no item GUID).
+
+- **Package:** `mssql@^12.6.0` (which pulls `tedious >= 19.2.2`). Older `tedious` (`<= 19.1.2`) has a LOGIN7 FeatureExt bug that causes "socket hang up" errors against Fabric endpoints.
+- **Encryption:** `encrypt: true` (not `'strict'`). This matches ODBC `Encrypt=yes`.
+- **Auth:** `azure-active-directory-access-token` with the token from `ctx.getToken(AudienceType.Sql)`.
+
+Install the driver in the functions project:
+
+```bash
+cd rayfin/functions
+npm install mssql@^12.6.0
+```
+
+| Resource               | What to pass as `server`                 | What to pass as `database`                 |
+| ---------------------- | ---------------------------------------- | ------------------------------------------ |
+| **Lakehouse**          | `sqlEndpointProperties.connectionString` | Item GUID (Initial Catalog — **required**) |
+| **Warehouse**          | `properties.connectionString`            | Item GUID                                  |
+| **SQL Database**       | `properties.serverFqdn`                  | `properties.databaseName`                  |
+| **Mirrored Database**  | SQL analytics endpoint                   | Item GUID                                  |
+| **Azure SQL Database** | Azure SQL server FQDN                    | Database name (no item GUID)               |
+
+> **Important:** For Lakehouse, Warehouse, and Mirrored Database you **must** pass the item GUID as `database`. Without it, multi-item workspaces cannot route the query correctly. Get these values via [Get Fabric info](./get-fabric-info.md).
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+import sql from "mssql";
+
+const udf = new UserDataFunctions();
+
+// Read these from the Fabric item — see "Get Fabric info".
+const SQL_SERVER = "<endpoint>.datawarehouse.fabric.microsoft.com";
+const DATABASE = "<item-guid-or-db-name>";
+
+udf.func(
+  "queryData",
+  async (
+    ctx: RayfinContext,
+    query: string,
+  ): Promise<Record<string, unknown>[]> => {
+    const token = ctx.getToken(AudienceType.Sql);
+    const pool = await sql.connect({
+      server: SQL_SERVER,
+      database: DATABASE,
+      options: { encrypt: true, trustServerCertificate: false },
+      authentication: {
+        type: "azure-active-directory-access-token",
+        options: { token },
+      },
+    });
+    const result = await pool.request().query(query);
+    await pool.close();
+    return result.recordset;
+  },
+  [udf.connection({ audienceType: AudienceType.Sql })],
+);
+```
+
+## OneLake files
+
+Read and write files in a Lakehouse's OneLake storage using `AudienceType.Storage`.
+
+The OneLake DFS URL has the form `https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<itemId>/Files/<path>` — get it from `oneLakeFilesPath` via [Get Fabric info](./get-fabric-info.md#lakehouse), or construct it from the workspace and item GUIDs.
+
+Call the DFS endpoint directly with the delegated token — no SDK required:
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "readFile",
+  async (ctx: RayfinContext, fileUrl: string): Promise<string> => {
+    const token = ctx.getToken(AudienceType.Storage);
+    const res = await fetch(fileUrl, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+      throw new Error(`OneLake read failed: ${res.status}`);
+    }
+    return await res.text();
+  },
+  [udf.connection({ audienceType: AudienceType.Storage })],
+);
+```
+
+## Eventhouse and KQL
+
+Query a Fabric **Eventhouse** (KQL database) or a standalone Azure Data Explorer cluster using `AudienceType.Kusto`.
+
+Get the cluster's **query URI** from the Eventhouse's `properties.queryServiceUri` — see [Get Fabric info → Eventhouse](./get-fabric-info.md#eventhouse).
+
+`azure-kusto-data` accepts a token provider, so hand it a callback that returns `ctx.getToken`:
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+import { Client, KustoConnectionStringBuilder } from "azure-kusto-data";
+
+const udf = new UserDataFunctions();
+
+// Read these from the Eventhouse item — see "Get Fabric info".
+const CLUSTER_URI = "https://<cluster>.z5.kusto.fabric.microsoft.com";
+const DATABASE = "<kql-database-name>";
+
+udf.func(
+  "queryKusto",
+  async (ctx: RayfinContext, query: string): Promise<unknown[]> => {
+    const kcsb = KustoConnectionStringBuilder.withTokenProvider(
+      CLUSTER_URI,
+      async () => ctx.getToken(AudienceType.Kusto),
+    );
+    const client = new Client(kcsb);
+    const response = await client.execute(DATABASE, query);
+    return response.primaryResults[0].toJSON().data;
+  },
+  [udf.connection({ audienceType: AudienceType.Kusto })],
+);
+```
+
+Install the SDK in the functions project:
+
+```bash
+cd rayfin/functions
+npm install azure-kusto-data
+```
+
+## Fabric REST API
+
+Call the [Fabric REST API](https://learn.microsoft.com/en-us/rest/api/fabric/) as the calling user — for example to list items or read item metadata from inside a function — using `AudienceType.Fabric`.
+
+The API base is fixed at `https://api.fabric.microsoft.com/v1`; `ctx.getToken(AudienceType.Fabric)` returns a token scoped for it. Send it as a bearer token with `fetch`:
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+const FABRIC_API = "https://api.fabric.microsoft.com/v1";
+
+udf.func(
+  "listWorkspaceItems",
+  async (ctx: RayfinContext, workspaceId: string): Promise<unknown> => {
+    const token = ctx.getToken(AudienceType.Fabric);
+    const res = await fetch(`${FABRIC_API}/workspaces/${workspaceId}/items`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+      throw new Error(`Fabric API returned ${res.status}`);
+    }
+    return res.json();
+  },
+  [udf.connection({ audienceType: AudienceType.Fabric })],
+);
+```
+
+> This is the same API used in [Get Fabric info](./get-fabric-info.md) — the difference is that there you call it at **authoring time** (with an `az` token) to gather endpoints, whereas here the **function** calls it at runtime with the user's delegated token.

package/assets/docs/functions/connections/add-foundry.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 4
+---
+
+# Add Azure AI Foundry
+
+Call an **Azure AI Foundry** (Azure OpenAI / Azure AI) resource from a function **as the signed-in user**, using `AudienceType.AzureAI`.
+
+Provide the resource **endpoint** (Azure AI Foundry → your resource → _Endpoint_). The token is a standard bearer token — send it with `fetch`, or wrap it with the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper for an Azure AI SDK client.
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+// Use your resource's real endpoint.
+const AI_ENDPOINT = "https://<resource>.services.ai.azure.com";
+
+udf.func(
+  "callAzureAi",
+  async (ctx: RayfinContext, prompt: string): Promise<unknown> => {
+    const token = ctx.getToken(AudienceType.AzureAI);
+    const res = await fetch(`${AI_ENDPOINT}/...`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ prompt }),
+    });
+    if (!res.ok) {
+      throw new Error(`Azure AI returned ${res.status}`);
+    }
+    return res.json();
+  },
+  [udf.connection({ audienceType: AudienceType.AzureAI })],
+);
+```
+
+Fill in the request path and body from the specific Azure AI API you are calling.
+
+See [Connecting to external resources](./index.md) for the shared connection model.

package/assets/docs/functions/connections/add-work-iq.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 6
+---
+
+# Add WorkIQ
+
+Call the **WorkIQ** service from a function **as the signed-in user**, using `AudienceType.WorkIQ`.
+
+Provide the **WorkIQ endpoint** you are calling. The token is a standard bearer token — send it with `fetch`:
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+// Use your real WorkIQ endpoint.
+const WORKIQ_ENDPOINT = "https://workiq.svc.cloud.microsoft/...";
+
+udf.func(
+  "callWorkIq",
+  async (ctx: RayfinContext): Promise<unknown> => {
+    const token = ctx.getToken(AudienceType.WorkIQ);
+    const res = await fetch(WORKIQ_ENDPOINT, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+      throw new Error(`WorkIQ returned ${res.status}`);
+    }
+    return res.json();
+  },
+  [udf.connection({ audienceType: AudienceType.WorkIQ })],
+);
+```
+
+See [Connecting to external resources](./index.md) for the shared connection model.

package/assets/docs/functions/connections/get-fabric-info.md

@@ -0,0 +1,159 @@
+---
+sidebar_position: 1
+---
+
+# Finding resource coordinates
+
+Every connection recipe needs a real endpoint — the SQL server, the OneLake path, the Key Vault URI, the Kusto query URI, and so on.
+This page explains **how to obtain those values from a Fabric item** so you (or an agent authoring a function) can fill them in with real data instead of guessing.
+
+**You only need the workspace and item _display names_ to start** — for example, "lakehouseA in workspaceB". Everything else (the workspace ID, item ID, SQL endpoint, OneLake path, Kusto URI) is derivable from here. Resolve those values rather than asking for anything you can look up.
+
+> **Why this matters:** don't hardcode a guessed endpoint. `ctx.getToken()` gives you an access token, but you still have to point the SDK at the correct URL — and that URL comes from the Fabric item's metadata, not from `process.env`.
+
+## Ways to get coordinates
+
+| Source                      | Best for                                                   | Notes                                                                               |
+| --------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **Fabric CLI** (e.g. `fab`) | Anyone who already has a Fabric CLI installed              | Wraps the REST API below. If you're already using a Fabric CLI, reach for it first. |
+| **Fabric MCP server**       | Agents running in an MCP-enabled environment               | If a Fabric MCP is configured, its tools wrap the same REST endpoints below.        |
+| **Fabric REST API**         | Automation, agents, reproducible lookups; no extra tooling | Canonical source. Returns endpoints/paths directly. Covered below.                  |
+| **Fabric portal**           | One-off manual lookups                                     | Open the item → **Settings** / **Connection strings** and copy the value.           |
+
+If a Fabric CLI or MCP tool is already available, prefer it — it wraps the same REST endpoints. Otherwise call the REST API directly; the portal is the fallback for a quick manual copy. The rest of this page uses the REST API, since that is the source of truth every other option wraps.
+
+## Calling the Fabric REST API
+
+- **Base URL:** `https://api.fabric.microsoft.com/v1`
+- **Token scope:** `https://api.fabric.microsoft.com/.default`
+- **Auth header:** `Authorization: Bearer <token>`
+
+Get a token at authoring time with the Azure CLI:
+
+```bash
+az account get-access-token \
+  --resource https://api.fabric.microsoft.com \
+  --query accessToken -o tsv
+```
+
+> This is an **authoring-time** lookup — you are gathering coordinates to write into the function. At **runtime** the function itself uses `ctx.getToken(AudienceType.X)` (or, for the Fabric API specifically, `ctx.getToken(AudienceType.Fabric)` — see [Add a Fabric resource → Fabric REST API](./add-fabric-resource.md#fabric-rest-api)).
+
+## Step 1 — find the workspace and item ID
+
+List workspaces you can access:
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces
+```
+
+List items of a given type in a workspace (to resolve a display name to its ID):
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items?type=Lakehouse
+```
+
+`type` accepts any Fabric item type — `Lakehouse`, `Warehouse`, `SQLDatabase`, `Eventhouse`, `KQLDatabase`, and so on.
+Each entry returns `id`, `displayName`, and `type`. Take the `id` of the item you want.
+
+## Step 2 — GET the item to read its coordinates
+
+Each item type has a typed endpoint that returns the connection coordinates in its `properties` object.
+
+### Lakehouse
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}
+```
+
+```json
+{
+  "id": "5b218778-e7a5-4d73-8187-f10824047715",
+  "type": "Lakehouse",
+  "properties": {
+    "oneLakeTablesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{itemId}/Tables",
+    "oneLakeFilesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{itemId}/Files",
+    "sqlEndpointProperties": {
+      "connectionString": "xxxxx.datawarehouse.fabric.microsoft.com",
+      "id": "37dc8a41-dea9-465d-b528-3e95043b2356",
+      "provisioningStatus": "Success"
+    }
+  }
+}
+```
+
+- **SQL analytics endpoint** → `properties.sqlEndpointProperties.connectionString` (the server for [SQL databases](./add-fabric-resource.md#sql-databases); use the lakehouse item GUID as `database`).
+- **OneLake Files / Tables** → `properties.oneLakeFilesPath` / `oneLakeTablesPath` (the DFS URLs for [OneLake files](./add-fabric-resource.md#onelake-files)).
+
+### Warehouse
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses/{warehouseId}
+```
+
+```json
+{
+  "type": "Warehouse",
+  "properties": {
+    "connectionString": "xxxxx.datawarehouse.fabric.microsoft.com"
+  }
+}
+```
+
+- **SQL server** → `properties.connectionString`. Use with [SQL databases](./add-fabric-resource.md#sql-databases); the warehouse item GUID is the `database`.
+
+### SQL Database
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlDatabases/{sqlDatabaseId}
+```
+
+```json
+{
+  "type": "SQLDatabase",
+  "properties": {
+    "connectionString": "Data Source=xxxxx.database.fabric.microsoft.com,1433;Initial Catalog=SQLDatabase1-<guid>;Encrypt=True;TrustServerCertificate=False",
+    "databaseName": "SQLDatabase1-<guid>",
+    "serverFqdn": "xxxxx.database.fabric.microsoft.com,1433"
+  }
+}
+```
+
+- **Server** → `properties.serverFqdn`, **database** → `properties.databaseName`. Both are also embedded in `properties.connectionString`.
+
+### Eventhouse
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/eventhouses/{eventhouseId}
+```
+
+```json
+{
+  "type": "Eventhouse",
+  "properties": {
+    "queryServiceUri": "https://xxxxx.z5.kusto.fabric.microsoft.com",
+    "ingestionServiceUri": "https://ingest-xxxxx.z5.kusto.fabric.microsoft.com",
+    "databasesItemIds": ["<kql-database-item-id>"]
+  }
+}
+```
+
+- **Cluster / query URI** → `properties.queryServiceUri`. Use with [Eventhouse and KQL](./add-fabric-resource.md#eventhouse-and-kql). Each KQL database inside the eventhouse is listed in `databasesItemIds`.
+
+## Coordinate lookup table
+
+| You need                       | Item type    | Endpoint                | Field                                               |
+| ------------------------------ | ------------ | ----------------------- | --------------------------------------------------- |
+| SQL server (Lakehouse)         | Lakehouse    | `.../lakehouses/{id}`   | `properties.sqlEndpointProperties.connectionString` |
+| SQL server (Warehouse)         | Warehouse    | `.../warehouses/{id}`   | `properties.connectionString`                       |
+| SQL server + database (SQL DB) | SQL Database | `.../sqlDatabases/{id}` | `properties.serverFqdn` / `properties.databaseName` |
+| OneLake Files / Tables URL     | Lakehouse    | `.../lakehouses/{id}`   | `properties.oneLakeFilesPath` / `oneLakeTablesPath` |
+| Kusto query URI                | Eventhouse   | `.../eventhouses/{id}`  | `properties.queryServiceUri`                        |
+| Item GUID (any item)           | any          | `.../items?type={Type}` | `id`                                                |
+
+For item types not listed here, browse the [Fabric REST API item reference](https://learn.microsoft.com/en-us/rest/api/fabric/) — each item's **Get** operation returns its coordinates under `properties`.
+
+## Notes
+
+- **OneLake paths are constructable.** Every OneLake path follows `https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{itemId}/Files/...` — if you already have the workspace and item GUIDs you can build the URL without a lookup.
+- **The item GUID is the `database` for SQL.** Fabric Lakehouse/Warehouse queries route by item GUID, not display name — see [SQL databases](./add-fabric-resource.md#sql-databases).
+- **Read permission required.** The `Get` endpoints need `Item.Read.All` (or the item-specific read scope) on the delegated token. If a lookup 403s, the signed-in user lacks read access to that item.