update iframe auth docs (#167)

* update iframe auth docs

* cellOnClick change

Author: andrewkenreich

content/workspace/developers/json-specs/widgets-json-reference.md

@@ -320,6 +320,11 @@ A `Widgets.json` table is a configuration structure with any of the named attrib
             _Example:_ `"id"`
             _Example use case:_ If your table displays company names in the cell but your API expects company IDs, set `valueField: "companyId"` to use the ID field from the row data instead of the displayed name.
 
+          - **forceUpdate**
+            _Type:_ `boolean` (optional)
+            By default, clicking a cell updates the shared parameter for the other widgets in the group, but the widget containing the clicked cell does not re-fetch its own data. Set this to `true` to force the source widget to update as well when one of its cells is clicked.
+            _Example:_ `true`
+
         - **colorValueKey**
           _Type:_ `string`
           Specifies which field to use for determining the color when showing cell changes.

content/workspace/developers/widget-configuration/render-functions.md

@@ -235,6 +235,32 @@ In this example:
 ]
 ```
 
+### Using forceUpdate to Refresh the Source Widget
+
+By default, when a cell click updates a parameter through the `groupBy` action, only the other widgets that share the parameter are refreshed — the widget containing the clicked cell does not re-fetch its own data. If the source widget also uses the parameter (for example, the table filters or highlights rows based on the selected symbol), set `forceUpdate: true` so it updates too:
+
+```json
+{
+    ...
+    "columnsDefs": [
+        {
+            "field": "symbol",
+            "headerName": "Symbol",
+            "renderFn": "cellOnClick",
+            "renderFnParams": {
+                "actionType": "groupBy",
+                "groupBy": {
+                    "paramName": "symbol",
+                    "forceUpdate": true
+                }
+            }
+        }
+    ]
+}
+```
+
+With `forceUpdate: true`, clicking a symbol cell updates the `symbol` parameter and re-fetches the table widget's own data in addition to updating the other widgets in the group.
+
 ### Hover Card
 
 To use the hover card render function, you need to add it to the `columnsDefs` array in your `widgets.json` file for the column you want to apply it to.

content/workspace/developers/widget-parameters/cell-click-grouping.md

@@ -229,3 +229,31 @@ In this example:
 - When displaying human-readable text but needing to pass IDs or codes
 - When the displayed value differs from the parameter value format
 - When you want to decouple the display value from the API parameter value
+
+## Using forceUpdate to Refresh the Source Widget
+
+By default, clicking a cell only updates the other widgets that share the parameter — the table widget containing the clicked cell does not re-fetch its own data. This avoids unnecessary requests, since the table usually just provides the selection.
+
+If the table widget itself also depends on the parameter (for example, it filters or highlights its rows based on the selected symbol), set `forceUpdate: True` in the `groupBy` configuration so the source widget re-fetches its data as well:
+
+```python
+{
+    "field": "symbol",
+    "headerName": "Symbol",
+    "cellDataType": "text",
+    "width": 120,
+    "renderFn": "cellOnClick",
+    "renderFnParams": {
+        "actionType": "groupBy",
+        "groupBy": {
+            "paramName": "symbol",
+            "forceUpdate": True  # Also re-fetch this widget's data on click
+        }
+    }
+}
+```
+
+**When to use forceUpdate:**
+
+- When the table widget's own endpoint uses the parameter being updated
+- When clicking a cell should refresh the data shown in the source table, not just the connected widgets

content/workspace/developers/widget-types/iframe.md

@@ -8,6 +8,8 @@ keywords:
 - streamlit
 - embed external app
 - postMessage
+- openbb-auth
+- auth headers
 - mcpUrl
 - destructiveHint
 - sub-widgets
@@ -24,6 +26,7 @@ On its own, an iframe just renders the URL. But by implementing the **Iframe Wid
 
 - **Export sub-widgets** — declare tables and markdown sections inside the iframe that Workspace can pull out as standalone dashboard widgets.
 - **Receive toolbar parameters** — react to Workspace parameters (dropdowns, dates, toggles) without a backend round-trip.
+- **Receive auth headers** — get the auth headers configured on the widget's backend connection, so the app can make authenticated API calls without re-prompting for credentials.
 - **Auto-connect an MCP server** — wire up Copilot tools the moment the widget mounts.
 - **Auto-refresh on mutating tool calls** — remount the iframe after a destructive MCP tool runs so the UI reflects new state.
 
@@ -92,6 +95,7 @@ The protocol is a small set of `postMessage` events exchanged between the embedd
 
 - **`openbb-request`** — Workspace asks the iframe for a sub-widget's data. A `widgetId` of `null` means "send everything."
 - **`openbb-params-update`** — Workspace pushes new toolbar parameter values to the iframe (e.g. the user changed a dropdown). The app reads these and re-renders.
+- **`openbb-auth`** — Workspace sends the widget's configured auth headers to the iframe in response to `openbb-connect`. See [Receiving auth headers](#receiving-auth-headers-openbb-auth).
 
 ### Sub-widget manifests
 
@@ -188,6 +192,49 @@ The bridge below is the complete client side of the protocol — announce on loa
 })();
 ```
 
+## Receiving auth headers (`openbb-auth`)
+
+If the widget's backend connection was configured with auth headers (for example an `Authorization` or `X-API-KEY` header entered when the backend was added to Workspace), Workspace forwards those headers to the embedded app so it can make authenticated requests of its own — for instance, calling the same backend the widget belongs to.
+
+The flow is part of the handshake:
+
+1. The embedded app sends `openbb-connect` (as in the [Minimal bridge](#minimal-bridge) above).
+2. Workspace replies with an `openbb-auth` message containing the configured headers:
+
+   ```js
+   {
+     type: "openbb-auth",
+     headers: { "Authorization": "Bearer ...", "X-API-KEY": "..." }
+   }
+   ```
+
+3. The app stores the headers and attaches them to its API calls:
+
+   ```js
+   let authHeaders = {};
+
+   window.addEventListener("message", function (event) {
+     if (event.data?.type === "openbb-auth") {
+       authHeaders = event.data.headers;
+       // e.g. re-fetch data now that credentials are available
+     }
+   });
+
+   // Later, in your data fetching:
+   fetch("https://my-backend.example.com/portfolio", { headers: authHeaders });
+   ```
+
+Because `openbb-auth` is only sent in reply to `openbb-connect`, register your `message` listener before (or at the same time as) sending the handshake, or the reply may arrive before you are listening.
+
+### Security constraints
+
+Workspace only sends `openbb-auth` when **both** of these hold:
+
+- The backend connection actually has headers configured — if there are none, no message is sent.
+- The `openbb-connect` message's origin **exactly matches** the origin of the iframe's `src` URL. The reply is posted targeted at that origin (never `"*"`), so credentials cannot leak to a different origin.
+
+The origin check means pages that send the handshake from a nested sub-frame on a *different* origin than the widget's `endpoint` URL (some component-based frameworks do this) will not receive the headers — send `openbb-connect` from the top-level page of your app in that case.
+
 ## Pushing parameters back to Workspace
 
 The protocol messages above cover the **inbound** direction — Workspace pushing parameter values *into* the iframe with `openbb-params-update`. The parameter bridge is the **outbound** direction: a widget pushes a new parameter value *back to* Workspace. Workspace persists the update and re-sends it to every widget [grouped](../json-specs/apps-json-reference) on that parameter, so one widget can drive the rest of the dashboard.