Header guide · Permissions-Policy

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.

Calls to getUserMedia() and getCurrentPosition() are refused by the policy because camera, microphone and geolocation are set to (); requestFullscreen() reaches the page because fullscreen is allowed for self.API CALLSPOLICYYOUR PAGEgetUserMedia()getCurrentPosition()requestFullscreen()cameramicrophonegeolocationfullscreen()()()(self)
camera=(), geolocation=() — the API calls are refused before any prompt.
In short5 points
  • 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.

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:

Shell
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.

Step by step

Configure it on your server

Setting up every header at once? Read all security headers on Apache, all security headers on Caddy, all security headers on Nginx, all security headers on Traefik.

Questions

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.

References

Sources

About the author

Portrait of Joshua Martinelle

Security engineer at Tenable

Security engineer at Tenable and web security researcher. He has disclosed more than 60 CVEs since 2020 and builds WebSec0.

Verify the change

Deployed it? Check it.

WebSec0 grades your TLS setup and security headers, including Permissions-Policy, in a few seconds. Free, no account.

Scan your site