# Permissions-Policy: syntax, features to disable and common errors

> Permissions-Policy switches off browser features such as camera, microphone and geolocation for your pages and iframes. Learn the syntax and which features to disable.

Author: Joshua Martinelle, Security engineer at Tenable (https://www.websec0.com/guides/authors/joshua-martinelle/)
Canonical: https://www.websec0.com/guides/permissions-policy/
Updated: 2026-10-16

## In short

- `Permissions-Policy` is an HTTP response header that lists browser features, such as the camera, microphone or geolocation, and which origins may use them in your page and its iframes.
- A disabled feature fails without asking the user: an injected or third-party script cannot prompt for the camera under your domain's name.
- The syntax is strict. `camera=()` disables a feature, `camera=(self)` keeps it for your origin, origins go in double quotes. One syntax error and Chrome ignores the whole header.
- Only Chromium-based browsers (Chrome, Edge) apply the header. Firefox and Safari ignore it, but they do apply the `allow` attribute on iframes.
- `interest-cohort` is obsolete: FLoC was cancelled in 2022. WebSec0 gives the full 15 points when the header parses and disables at least one sensitive feature, such as the camera, with `()`.

## What is Permissions-Policy?

**Permissions-Policy is an HTTP response header that tells the browser which
features your page and its iframes may use, and from which origins.** The
features are powerful browser APIs such as the camera, the microphone,
geolocation, payments or USB devices. When a feature is disabled, the API
fails straight away and the user is never asked.

A typical header looks like this:

```http
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=()
```

Each `feature=()` switches that feature off for the page and every iframe in
it. The header replaced `Feature-Policy`, which used a different syntax and is
deprecated.

Support is limited to Chromium. MDN's compatibility data lists the header in
Chrome and Edge, from version 88 for most features, and not in Firefox or
Safari. Those two do apply the `allow` attribute on iframes, covered below.

Adoption is growing. In Scott Helme's June 2026 crawl, 101,364 of the 819,002
top sites that responded sent `Permissions-Policy` (about 12%), three times the
2022 figure. Among them, about 80% restricted geolocation, the microphone and
the camera.

## What it protects against

Permission prompts carry your domain name. Users who trust your site may
accept a camera or location prompt that was triggered by code you did not
write.

| Threat | What Permissions-Policy does |
| --- | --- |
| A compromised third-party script asks for the camera, microphone or location | The call fails without a prompt. |
| An ad or widget iframe uses payment, USB or sensor APIs | Iframes cannot use a feature the page has disabled. |
| An XSS payload escalates to device access | The features you switched off stay off. |
| A feature delegated to an iframe you did not mean to trust | Only origins in the allowlist can use it. |

Permissions-Policy only removes capabilities. It never grants a permission:
when a feature is allowed, the browser still asks the user. It also does not
stop script injection itself; that is the job of the
[Content-Security-Policy header](/guides/content-security-policy/).

## The syntax

The header is a list of `feature=allowlist` pairs separated by commas. The
allowlist says where the feature is allowed:

| Allowlist | Meaning |
| --- | --- |
| `feature=()` | Disabled everywhere, including your own page |
| `feature=(self)` | Your origin only, and same-origin iframes |
| `feature=(self "https://video.example")` | Your origin and that origin's iframes |
| `feature=*` | Any origin |
| Feature not listed | Its default: usually `self` |

The format is a Structured Field dictionary (RFC 9651), and browsers parse it
strictly:

- Feature names are lower case.
- No spaces around `=`.
- `self` and `*` are written bare. Origins are strings, in double quotes.
- Features are separated by commas, with no trailing comma.

Chrome treats errors in two different ways. A syntax error makes it ignore
**the whole header**, with an error in the console: "Parse of permissions
policy failed". A valid header with an odd value only loses that value. What
we saw in Chrome 152:

| Header sent | Result |
| --- | --- |
| `camera=(), microphone=()` | Both disabled |
| `Camera=(), microphone=()` | Whole header ignored: upper-case name |
| `camera = (), microphone=()` | Whole header ignored: spaces around `=` |
| `camera=('self'), microphone=()` | Whole header ignored: quoted `self` |
| `camera=(), microphone=(),` | Whole header ignored: trailing comma |
| `camera 'none'; microphone 'none'` | Whole header ignored: old Feature-Policy syntax |
| `camera=(self https://video.example)` | Origin ignored, with a warning: not in double quotes |
| `interest-cohort=(), camera=()` | Camera disabled: the obsolete feature is skipped |

Unknown feature names are skipped silently, so a feature that only exists in
newer browsers does not break the header.

## Which features to disable

Disable every powerful feature your site does not use. This header covers the
usual list:

```http
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()
```

| Feature | Controls | Keep it if |
| --- | --- | --- |
| `camera`, `microphone` | `getUserMedia()` | You run video or voice calls |
| `geolocation` | `navigator.geolocation` | You show a map of the user's position |
| `payment` | The Payment Request API | You or your checkout iframe use it |
| `usb`, `serial`, `hid`, `bluetooth`, `midi` | Access to devices | You build a hardware tool |
| `display-capture` | Screen sharing | You run screen sharing |
| `accelerometer`, `gyroscope`, `magnetometer` | Motion sensors | You build a motion or VR experience |
| `browsing-topics` | The Topics advertising API | Never, unless you serve ads that rely on it |

Leave out features you are unsure about rather than disabling them. Some
affect common flows: `fullscreen` blocks video players from going full
screen, and `publickey-credentials-get` blocks passkey sign-in.

## interest-cohort and browsing-topics

`interest-cohort=()` was the opt-out for FLoC, an advertising experiment
Google cancelled in 2022. In our test, Chrome 152 still accepted the name
without a warning, but the API behind it, `document.interestCohort()`, no
longer exists. In June 2026, 5,872 sites still sent it. It does no harm, but
remove it.

`browsing-topics=()` opts out of the Topics API, which replaced FLoC. Chrome
announced in November 2025 that Topics would be deprecated and removed with
the other Privacy Sandbox APIs. In our Chrome 152 test the API was still
present, so keep `browsing-topics=()` for now if you want the opt-out.

## Allowing a feature in an iframe

An embedded video call or map needs two things for a feature to work in a
cross-origin iframe:

1. **The header allows that origin.**
2. **The iframe's `allow` attribute requests the feature.**

```http
Permissions-Policy: camera=(self "https://meet.example"), microphone=(self "https://meet.example"), geolocation=()
```

```html
<iframe src="https://meet.example/room/42" allow="camera; microphone"></iframe>
```

The browser applies the most restrictive combination of the two. Firefox and
Safari ignore the header but apply `allow`, so always set the attribute on
iframes that need a feature, and leave it off the others.

## Where to send the header

- **On every HTML response,** including error pages. The policy applies to
  the document and to every iframe inside it.
- **Once per response.** Several headers are combined, and when a feature
  appears twice the last definition wins. In our test, `camera=()` followed by
  a second header `camera=*` left the camera allowed.
- **With one owner.** Decide whether the application or the web server sends
  the header, and remove it from the other.

Check what a page sends with `curl`, then open the browser console on the
page to catch parse errors:

```sh
curl -sI https://example.com/ | grep -i "^permissions-policy"
```

## Common mistakes

- **Copying the Feature-Policy syntax.** `camera 'none'` in a
  Permissions-Policy header makes Chrome ignore the whole header.
- **Quoting `self` or leaving origins bare.** Write `(self "https://a.example")`,
  not `('self' https://a.example)`.
- **Disabling a feature you use.** `payment=()` or `fullscreen=()` can break a
  checkout or a video player. Test the pages that use them.
- **Allowing an origin without the `allow` attribute,** or the reverse. A
  cross-origin iframe needs both.
- **Two headers with different values.** The last definition of each feature
  wins.
- **Writing `none`.** It is not a keyword. `camera=none` happens to disable the
  camera, with a console warning; write `camera=()`.
- **Expecting it to work in Firefox or Safari.** Only the `allow` attribute
  works there.

## How WebSec0 grades Permissions-Policy

Permissions-Policy is worth **15 of the 100 points** in the WebSec0 headers
grade. The scanner fetches your page, joins every `Permissions-Policy` header
and parses the result the way Chrome does. It then looks at ten sensitive
features: `camera`, `microphone`, `geolocation`, `payment`, `usb`, `serial`,
`hid`, `bluetooth`, `midi` and `display-capture`.

| What WebSec0 sees | Status | Points |
| --- | --- | --- |
| No `Permissions-Policy` header | Fail | 0 / 15 |
| A header that does not parse, which browsers ignore | Fail | 0 / 15 |
| A valid policy that disables none of the sensitive features | Warning | 7 / 15 |
| A sensitive feature opened to every origin with `*` | Warning | 7 / 15 |
| At least one sensitive feature disabled with `()`, none opened with `*` | Pass | 15 / 15 |

A few details follow from how the check works:

- **Only `()` counts as disabling.** These features already default to
  `self`, so `camera=(self)` restricts nothing. Delegating a feature to a
  named origin, `camera=(self "https://meet.example")`, is neither penalised
  nor counted as disabled.
- **The last definition wins,** as in the browser. `camera=()` followed by a
  second header `camera=*` is a warning.
- **`interest-cohort=()` or `fullscreen=(self)` alone is a warning.** Neither
  touches a sensitive feature.
- **`Feature-Policy` is not graded.** A site sending only the old header
  fails the check.

## Frequently asked questions

### What does the Permissions-Policy header do?

It tells the browser which powerful features, such as the camera, microphone, geolocation or USB, your page and the iframes inside it may use, and from which origins. A feature that is not allowed fails immediately, without prompting the user.

### What should my Permissions-Policy contain?

Disable every powerful feature your site does not use: `camera=(), microphone=(), geolocation=(), payment=(), usb=()` and so on. Keep `(self)`, or add the iframe origins that need it, for features you do use.

### Do Firefox and Safari support Permissions-Policy?

Not the header. MDN's compatibility data lists it in Chrome and Edge only. Firefox and Safari support the `allow` attribute on iframes, so delegate features with `allow` as well as with the header.

### What is the difference between Feature-Policy and Permissions-Policy?

Feature-Policy is the deprecated first version, with a different syntax: `camera 'none'`. Permissions-Policy replaced it in Chromium browsers and uses a structured syntax: `camera=()`. Do not put the old syntax in the new header: Chrome ignores the whole header.

### Should I still send interest-cohort=()?

No. It opted out of FLoC, which Google cancelled in 2022. Chrome still accepts the name without a warning, so it does no harm, but it does nothing either.

### Why is my Permissions-Policy ignored?

Usually a syntax error: an upper-case feature name, spaces around `=`, `'self'` with quotes, an origin without double quotes in a list or a trailing comma. Chrome then ignores the entire header and logs an error in the console.

### How do I allow the camera in an embedded iframe?

Allow the iframe's origin in the header, `camera=(self "https://meet.example")`, and add `allow="camera"` to the iframe. Both are needed: the browser applies the most restrictive of the two.

### Does Permissions-Policy give my site access to the camera?

No. It can only restrict features. When a feature is allowed, the browser still asks the user for permission as usual.

## Sources

- [Permissions Policy](https://w3c.github.io/webappsec-permissions-policy/), W3C
- [Policy-controlled features](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md), W3C
- [RFC 9651: Structured Field Values for HTTP](https://www.rfc-editor.org/rfc/rfc9651.html), IETF
- [Permissions-Policy header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy), MDN Web Docs
- [Permissions Policy guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Permissions_Policy), MDN Web Docs
- [Intent to Deprecate and Remove: Topics API](https://groups.google.com/a/chromium.org/g/blink-dev/c/_R85yctz4Rs), Chromium blink-dev
- [Top 1 Million analysis, June 2026: ten years of web security](https://scotthelme.co.uk/top-1-million-analysis-june-2026-ten-years-of-web-security/), Scott Helme
