A page embeds a cross-origin map widget with <iframe src="https://maps.example/w" allow="geolocation">, and geolocation inside the frame still fails immediately without ever prompting the user. The same widget works when opened as a top-level page. What does Permissions-Policy have to do with it?

## Two independent gates A powerful feature inside a frame has to clear two entirely separate checks, and confusing them wastes hours of debugging. 1. **Permissions Policy** — is this document *allowed to ask*? Decided by the embedder chain and HTTP response headers, with no user involvement. 2. **The user's permission** — has the user *said yes*? Decided by the browser's prompt and stored per origin. The tell-tale symptom of a policy failure is that nothing is displayed to the user. The geolocation error callback fires immediately, or a promise rejects with `NotAllowedError`, and no prompt ever appears. When the user is genuinely being asked and refusing, you see the prompt. ## The intersection rule Every document has an allowlist per feature, and a nested document's allowlist is the intersection of what its parent holds and what its parent chooses to hand down. Two consequences follow. First, a frame can never gain a feature its embedder lacks. If the top-level document has disabled geolocation for itself, no container markup, however permissive, restores it for a child. Second, the top-level document's own allowlist comes from its `Permissions-Policy` response header, or from the feature's **default allowlist** if no header is sent. For the powerful features — geolocation, camera, microphone, display capture — the default is `self`, meaning "the top-level origin and same-origin descendants". That is why a cross-origin widget is off by default and why the failure appears only after embedding. ## The header `Permissions-Policy` is an HTTP response header using structured-fields syntax: a comma-separated list of `feature=allowlist` entries, where the allowlist is a parenthesised list containing the bare token `self`, quoted origins, or the wildcard `*`; an empty list `()` disables the feature entirely. ```http Permissions-Policy: geolocation=(self "https://maps.example"), camera=(), fullscreen=* ``` That example permits geolocation for the document's own origin plus the map widget's origin, disables the camera outright for the page and everything it embeds, and allows fullscreen anywhere in the tree. Note that a mistyped or unknown feature name is ignored rather than reported, so a policy that "has no effect" is often a spelling problem. `Feature-Policy` is the deprecated predecessor of this header; new deployments should send `Permissions-Policy`, and browsers that still honour the old name treat it as a fallback. ## Debugging the failure The efficient order is: 1. Load the widget as a top-level page. If it works there, the widget is fine and the embedding chain is the problem — which is exactly the observation in this question. 2. Look at the top-level document's response headers for `Permissions-Policy`. A missing header is not neutral; it means the default allowlist applies. 3. Walk the whole ancestor chain, not just the immediate parent. In a nested arrangement, an intermediate frame that does not pass the feature down truncates it for everything beneath. 4. Confirm the frame is in a secure context, since powerful features require one regardless of policy. Chromium's DevTools surfaces the computed policy for a selected frame, which short-circuits most of this. ## Why the design is shaped this way Without it, embedding any third-party content would silently expose every capability the embedding origin holds. A user who granted your site their location would be granting it to every advertisement, analytics frame and social widget you host, with the prompt attributed to your origin — because permissions are keyed on the top-level site, not on whoever is technically making the call. Requiring an explicit, per-origin delegation makes exposure a deliberate act by the embedder. It also gives a site a way to bind its own hands. Sending `Permissions-Policy: camera=(), microphone=(), geolocation=()` on a page that legitimately needs none of them means a script injected into that page cannot use them either. That is a real hardening measure and one of the more underused headers on the platform. ## The half that is still the user's Delegation only opens the door. When the widget calls the geolocation API in a properly delegated frame and the user has not decided, the browser prompts — and the prompt names the **top-level site**, not the embedded origin, because that is the site the user believes they are dealing with. A stored grant therefore attaches to the top-level site, so a user who already allowed your site is not prompted a second time when the widget asks. That is a strong reason to be conservative about which origins you delegate to: from the user's point of view, they said yes to you.