Skip to content

Update and clarify Permissions-Policy usage #42534

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chrisdavidmills merged 2 commits into from
Jan 27, 2026
Merged

Update and clarify Permissions-Policy usage #42534

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f35e594
Update and clarify Permissions-Policy usage
bban160 Jan 26, 2026
d393519
Minor language tweaks
bban160 Jan 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 14 additions & 13 deletions files/en-us/web/http/reference/headers/permissions-policy/bluetooth/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,36 +30,37 @@ Permissions-Policy: bluetooth=<allowlist>;

## Default policy

The default allowlist for `bluetooth` is `self`.
The default allowlist for `bluetooth` is `self`. The top-level browsing context and same-origin iframes are allowed access to the `bluetooth` feature by default.

## Examples

### General example
### Basic usage

SecureCorp Inc. wants to disable the Web Bluetooth API within all browsing contexts except for its own origin and those whose origin is `https://example.com`.
It can do so by delivering the following HTTP response header to define a Permissions Policy:
SecureCorp Inc. wants to disallow `bluetooth` within all cross-origin iframes except those whose origin is `https://example.com`. It can do so by delivering the following HTTP response header to define a Permissions Policy:

```http
Permissions-Policy: bluetooth=(self "https://example.com")
```

### With an \<iframe> element
SecureCorp Inc. must also include an {{HTMLElement('iframe','allow','#Attributes')}} attribute on each `<iframe>` element where `bluetooth` is to be allowed:

FastCorp Inc. wants to disable `bluetooth` for all cross-origin child frames, except for a specific `<iframe>`.
It can do so by delivering the following HTTP response header to define a Permissions Policy:

```http
Permissions-Policy: bluetooth=(self https://other.com/blue)
```html
<iframe src="https://example.com/blue" allow="bluetooth"></iframe>
```

Then include an {{HTMLElement('iframe','allow','#Attributes')}} attribute on the `<iframe>` element:
> [!NOTE]
> Specifying the `Permissions-Policy` header in this manner disallows `bluetooth` for other origins, even if they are allowed by the `<iframe>` `allow` attribute.

### Using the default policy

If an allowlist for `bluetooth` is not defined by a `Permissions-Policy` response header, user agents will apply the default allowlist `self`. In this mode, `bluetooth` is automatically allowed in the top-level browsing context and same-origin iframes, but not in cross-origin iframes.

To allow `bluetooth` in a cross-origin iframe, include an {{HTMLElement('iframe','allow','#Attributes')}} attribute on the `<iframe>` element:

```html
<iframe src="https://other.com/blue" allow="bluetooth"></iframe>
```

`<iframe>` attributes can selectively enable features in certain frames, and not in others, even if those frames contain documents from the same origin.

## Specifications

{{Specifications}}
Expand Down
27 changes: 14 additions & 13 deletions files/en-us/web/http/reference/headers/permissions-policy/fullscreen/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,6 @@ sidebar: http

The HTTP {{HTTPHeader("Permissions-Policy")}} header `fullscreen` directive controls whether the current document is allowed to use {{domxref('Element.requestFullscreen()')}}.

By default, top-level documents and their same-origin child frames can request and enter fullscreen mode. This directive allows or prevents cross-origin frames from using fullscreen mode. This includes same-origin frames.

Specifically, where a defined policy blocks use of this feature, {{domxref('Element.requestFullscreen', "requestFullscreen()")}} calls will return a {{jsxref('Promise')}} that rejects with a {{jsxref('TypeError')}}.

> [!NOTE]
Expand All @@ -31,34 +29,37 @@ Permissions-Policy: fullscreen=<allowlist>;

## Default policy

The default allowlist for `fullscreen` is `self`.
The default allowlist for `fullscreen` is `self`. The top-level browsing context and same-origin iframes are allowed access to the `fullscreen` feature by default.

## Examples

### General example
### Basic usage

SecureCorp Inc. wants to disable the Fullscreen API within all browsing contexts except for its own origin and those whose origin is `https://example.com`. It can do so by delivering the following HTTP response header to define a Permissions Policy:
SecureCorp Inc. wants to disallow `fullscreen` within all cross-origin iframes except those whose origin is `https://example.com`. It can do so by delivering the following HTTP response header to define a Permissions Policy:

```http
Permissions-Policy: fullscreen=(self "https://example.com")
```

### With an \<iframe> element

FastCorp Inc. wants to disable `fullscreen` for all cross-origin child frames, except for a specific `<iframe>`. It can do so by delivering the following HTTP response header to define a Permissions Policy:
SecureCorp Inc. must also include an {{HTMLElement('iframe','allow','#Attributes')}} attribute on each `<iframe>` element where `fullscreen` is to be allowed:

```http
Permissions-Policy: fullscreen=(self)
```html
<iframe src="https://example.com/presentation" allow="fullscreen"></iframe>
```

Then include an {{HTMLElement('iframe','allow','#Attributes')}} attribute on the `<iframe>` element:
> [!NOTE]
> Specifying the `Permissions-Policy` header in this manner disallows `fullscreen` for other origins, even if they are allowed by the `<iframe>` `allow` attribute.

### Using the default policy

If an allowlist for `fullscreen` is not defined by a `Permissions-Policy` response header, user agents will apply the default allowlist `self`. In this mode, `fullscreen` is automatically allowed in the top-level browsing context and same-origin iframes, but not in cross-origin iframes.

To allow `fullscreen` in a cross-origin iframe, include an {{HTMLElement('iframe','allow','#Attributes')}} attribute on the `<iframe>` element:

```html
<iframe src="https://other.com/videoplayer" allow="fullscreen"></iframe>
```

iframe attributes can selectively enable features in certain frames, and not in others, even if those frames contain documents from the same origin.

## Specifications

{{Specifications}}
Expand Down
37 changes: 15 additions & 22 deletions files/en-us/web/http/reference/headers/permissions-policy/geolocation/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,6 @@ Specifically, where a defined policy blocks use of this feature, calls to
callbacks to be invoked with a {{domxref('GeolocationPositionError')}} code of
`PERMISSION_DENIED`.

By default, the Geolocation API can be used within top-level documents and their
same-origin child frames. This directive allows or prevents cross-origin frames from
accessing geolocation. This includes same-origin frames.

## Syntax

```http
Expand All @@ -36,40 +32,37 @@ Permissions-Policy: geolocation=<allowlist>;

## Default policy

The default allowlist for `geolocation` is `self`.
The default allowlist for `geolocation` is `self`. The top-level browsing context and same-origin iframes are allowed access to the `geolocation` feature by default.

## Examples

### General example
### Basic usage

SecureCorp Inc. wants to disable the Geolocation API within all browsing contexts
except for its own origin and those whose origin is `https://example.com`. It
can do so by delivering the following HTTP response header to define a Permissions Policy:
SecureCorp Inc. wants to disallow `geolocation` within all cross-origin iframes except those whose origin is `https://example.com`. It can do so by delivering the following HTTP response header to define a Permissions Policy:

```http
Permissions-Policy: geolocation=(self "https://example.com")
```

### With an \<iframe> element

FastCorp Inc. wants to disable `geolocation` for all cross-origin child
frames, except for a specific `<iframe>`. It can do so by delivering the following
HTTP response header to define a Permissions Policy:
SecureCorp Inc. must also include an {{HTMLElement('iframe','allow','#Attributes')}} attribute on each `<iframe>` element where `geolocation` is to be allowed:

```http
Permissions-Policy: geolocation=(self)
```html
<iframe src="https://example.com/map" allow="geolocation"></iframe>
```

Then include an {{HTMLElement('iframe','allow','#Attributes')}} attribute on the
`<iframe>` element:
> [!NOTE]
> Specifying the `Permissions-Policy` header in this manner disallows `geolocation` for other origins, even if they are allowed by the `<iframe>` `allow` attribute.

### Using the default policy

If an allowlist for `geolocation` is not defined by a `Permissions-Policy` response header, user agents will apply the default allowlist `self`. In this mode, `geolocation` is automatically allowed in the top-level browsing context and same-origin iframes, but not in cross-origin iframes.

To allow `geolocation` in a cross-origin iframe, include an {{HTMLElement('iframe','allow','#Attributes')}} attribute on the `<iframe>` element:

```html
<iframe src="https://other.com/map" allow="geolocation"></iframe>
<iframe src="https://other.com/store-locator" allow="geolocation"></iframe>
```

Interestingly, `allow` attributes can selectively enable features in certain frames, and not in others,
even if those frames contain documents from the same origin.

## Specifications

{{Specifications}}
Expand Down