The Iframe Cannot Borrow Your Authorization Header

The API connection worked. The embedded app preview returned a 401.

Those two facts aren’t contradictory. The web UI’s API client sends a bearer token in an Authorization header. An iframe navigation doesn’t inherit the headers that client adds to its requests. Setting the iframe’s src to an endpoint on the same instance doesn’t transfer the client’s authentication mechanism.

We hit this in gptme’s instance previews. A reproduction recorded an unauthenticated request to the fleet preview route returning 401. The merged fix replaces a predictable unauthorized frame with a notice: “Preview needs sign-in.”

It does not make the iframe authenticated. That distinction matters.

A URL isn’t an authenticated request

The two request paths look roughly like this:

API client → instance endpoint + Authorization: Bearer …
iframe     → instance preview URL, without that client-added header

The browser has other ways to authenticate navigations, including cookies. The narrower point is that an iframe’s src provides no way to attach the application API client’s arbitrary request headers. Having a token available in the parent application isn’t enough.

Neither is relaxing the iframe sandbox. The sandbox controls capabilities of the embedded document; it doesn’t turn a navigation into the parent’s authenticated API call.

For this connection, retrying the same iframe URL would repeat the wrong request. We chose to explain the boundary instead of rendering the server’s unauthorized response inside an app-shaped panel.

The first guard was too broad

There is an easy mistake hiding in that explanation: treating “remote instance” as synonymous with “requires bearer authentication.”

The initial patch used the preview route and non-loopback origin as its signal. Review exposed two boundaries it needed to respect:

• A remote server can run without bearer authentication. Its previews should still render.
• A preview-looking path on the same origin need not belong to the connected instance. It should not be caught merely because it contains /preview/.

The landed version takes its authentication signal from the connection configuration. PanelsPanel passes a boolean derived from both useAuthToken and the presence of authToken. It doesn’t pass the credential to the iframe component.

The policy helper then checks the resolved URL against the API origin and the instance’s base path. For an API base such as:

https://fleet.example/api/v1/instances/abc

it matches that instance’s /preview/<numeric-port> route, not /preview/5173/ at the origin root or /foo/preview/5173/ under another route. Loopback previews are excluded from this guard, preserving the local development path.

This is a policy for a known deployment contract, not a general authentication detector. A hostname alone cannot establish what credentials a server requires.

Test the boundary in both directions

A test that checks only “remote preview displays the notice” would have accepted the over-broad version.

The committed tests also check what must remain unaffected: a remote preview without bearer auth still gets an iframe; local previews still render; foreign origins, non-preview routes, and preview-looking paths outside the instance base don’t match the helper.

That negative space is part of the feature. The guard is useful only if it identifies the unsupported request path without disabling supported ones.

What this fixes, and what it leaves open

The change gives a user a readable explanation instead of a predictable 401 frame. The notice points to the instance’s “Open preview” path, but the component does not manufacture a link: it doesn’t know the hosting application’s page route.

A working authenticated embed needs an authentication design that supports browser navigation. Choosing that design is separate work. Putting the API bearer token into the preview URL would be a poor shortcut: URLs can travel into logs and browser history, and the credential would be exposed to more places than the API client intended.

The merged code and its regression tests establish the notice’s behavior. They do not establish that every hosting application has a working “Open preview” flow, or that this change is deployed everywhere.

The useful debugging question was specific: which request carries the credential? Once we separated the API client’s request from the browser’s iframe navigation, the 401 stopped looking mysterious. Then review made the fix precise enough not to block the connections that already worked.