HTTP Headers

Permissions Policy

HTTP Header

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The HTTP Permissions-Policy response header provides a mechanism to allow and deny the use of browser features in a document or within any

elements in the document.

For more information, see the main Permissions Policy article.

Syntax

http

Permissions-Policy: <directive>=<allowlist>

The Permissions Policy directive to apply the allowlist to. See Directives below for a list of permitted directive names.
An allowlist is a list of origins that takes one or more of the following values contained in parentheses, separated by spaces:

* (wildcard): The feature will be permitted in this document and all nested browsing contexts (<iframe> elements), regardless of their origin.
() (empty allowlist): The feature is disabled in both top-level and nested browsing contexts. For <iframe> allow attributes, this is equivalent to 'none'.
self: The feature will be permitted in this document and all nested browsing contexts originating from the same domain. It is shorthand for the current origin, such as https://your-site.example.com. In <iframe> allow attributes, it is referenced as self.
src: The feature will be permitted in this <iframe> as long as the loaded document matches the domain of the src URL. This value is used only in the <iframe> allow attribute and is its default allowlist value.
"<origin>": The feature is permitted for specific origins, such as "https://a.example.com". Multiple origins can be listed, separated by spaces. Origins in <iframe> allow attributes are not quoted.

The values * and () are mutually exclusive and should be used alone. self and src can be combined with origins.

Note:
Each directive has a default allowlist — typically *, self, or none — for the Permissions-Policy header. For the <iframe> allow attribute, the default is always src.

Where supported, wildcards can simplify permission policy origins. Instead of listing each subdomain individually, you can use a wildcard:

Instead of:

http

("https://example.com" "https://a.example.com" "https://b.example.com" "https://c.example.com")

You can write:

http

("https://example.com" "https://*.example.com")

Note: "https://*.example.com" does not match "https://example.com".

Directives

Device Access and Feature Control

Web browsers implement various security policies to control access to device features and APIs. These policies help protect user privacy and security by restricting or allowing specific capabilities for websites and web applications. Below is a comprehensive overview of different directives that browsers may enforce, along with their purposes.

accelerometer: Determines whether the current document is permitted to access device acceleration data through the Accelerometer interface.
ambient-light-sensor: Controls whether the document can access information about ambient light levels via the AmbientLightSensor interface.
attribution-reporting: Specifies if the document can use the Attribution Reporting API, which is used for privacy-preserving ad attribution.
autoplay: Indicates whether media elements can autoplay content without user interaction. If disabled, scripts calling play() will reject with a NotAllowedError.
bluetooth: Controls whether the Web Bluetooth API is enabled, affecting the ability to connect to Bluetooth devices via scripts.
browsing-topics: Regulates access to the Topics API, which enables interest-based content categorization.
camera: Controls whether the document can access video input devices like webcams.
compute-pressure: Allows control over access to the Compute Pressure API, used for monitoring CPU load.
cross-origin-isolated: Determines if the document can be treated as cross-origin isolated, enabling advanced features requiring such isolation.
deferred-fetch: Manages quota for top-level fetch requests initiated with fetchLater().
deferred-fetch-minimal: Controls the allocation of quotas for shared cross-origin subframe fetch requests using fetchLater().
display-capture: Enables or disables permission to capture screen contents using getDisplayMedia().
document-domain: Controls whether the page can modify the document.domain property, typically used in cross-origin communication.
encrypted-media: Regulates access to the Encrypted Media Extensions API (EME) for digital rights management content.
fullscreen: Controls if the element can enter fullscreen mode via requestFullscreen().
gamepad: Manages access to gamepad hardware via the Gamepad API.
geolocation: Determines whether the document can access geolocation information with methods like getCurrentPosition().
gyroscope: Controls access to orientation data through the Gyroscope interface.
hid: Enables or disables interaction with Human Interface Devices (HID) via the WebHID API.
identity-credentials-get: Regulates whether the document can access federated credentials using navigator.credentials.get() with identity options.
idle-detection: Controls the ability to use the Idle Detection API to determine user activity status.
local-fonts: Allows websites to query locally-installed fonts using the Local Font Access API.
magnetometer: Controls access to device magnetic field sensor data via the Magnetometer interface.
microphone: Determines whether the webpage can access audio input devices like microphones.
midi: Enables or disables access to MIDI devices through the Web MIDI API.
otp-credentials: Controls permission to retrieve one-time passwords (OTPs) via the WebOTP API, typically from SMS messages.
payment: Regulates whether the Payment Request API can be used to initiate payment flows.
picture-in-picture: Controls the ability to use Picture-in-Picture mode for videos.
publickey-credentials-create: Determines if websites can create new public key credentials via the Web Authentication API.
publickey-credentials-get: Controls whether existing public key credentials can be retrieved using the Web Authentication API.
screen-wake-lock: Enables pages to prevent the device screen from dimming or turning off via the Screen Wake Lock API.
serial: Controls access to serial port communication through the Web Serial API.
speaker-selection: Allows websites to list and select audio output devices.
storage-access: Regulates third-party embedded documents’ access to unpartitioned cookies via the Storage Access API.
summarizer: Controls access to the Summarizer API, which may be used for AI-based text summarization.
usb: Enables or disables interaction with USB devices via the WebUSB API.
web-share: Controls whether pages can share content via the Web Share API.
window-management: Regulates ability to manage windows across multiple displays with the Window Management API.
xr-spatial-tracking: Controls access to WebXR Device API for interacting with XR sessions with spatial tracking.

Example

Examples

Basic usage

Permissions-Policy headers control access to browser features. To allow all origins access to geolocation, use the following header:

Header: Permissions-Policy: geolocation=*

Alternatively, to permit access only to specific origins, use:

Header: Permissions-Policy: geolocation=(self “https://a.example.com” “https://b.example.com”)

Multiple features can be managed simultaneously by including them in one comma-separated list within a single header, or by separate headers. For example, these configurations are equivalent:

Header 1: Permissions-Policy: picture-in-picture=(), geolocation=(self https://example.com/), camera=*

Header 2: Permissions-Policy: picture-in-picture=()
Permissions-Policy: geolocation=(self https://example.com/)
Permissions-Policy: camera=*

iframes

For an <iframe> element to have a feature enabled, its allowed origin must also be in the allowlist of the parent page. Due to inheritance behavior, it’s beneficial to set the broadest support in the HTTP headers and then specify narrower support within each <iframe> element.

To enable all origins’ access to geolocation within an iframe, write:

To restrict access to specific origins, apply:

Multiple feature controls can be added within the same iframe allow attribute using semi-colon-separated directives:

The src attribute’s value influences feature allowance: features are permitted for documents loaded from the same origin as the src URL by default. This default behavior mirrors the allowlist configuration.

For example:

Denying access to powerful features

To disable sensitive features like microphone and geolocation APIs across all contexts, specify empty policies:

<p>Permissions-Policy: microphone=(), geolocation=()</p>

This universally blocks these features, regardless of iframe origins.

Combining HTTP header and <iframe> policies

Suppose you want to enable geolocation on your own origin and on trusted ad network iframes, but restrict it elsewhere. You could set the header:

<p>Permissions-Policy: geolocation=(self https://trusted-ad-network.com)</p>

And, within trusted ad iframes, specify:

For other origins, geolocation would be disabled:

How to Modify Header using Requestly

Requestly is a versatile Chrome extension that also lets you modify the Permissions Policy header. Modifying this header can help you control which browser features and APIs are available to your web pages, enhancing security or compatibility during development and testing. Steps to Modify the Permissions Policy Header:

Install and open the Requestly Chrome extension. You can find it on the Chrome Web Store.
Create a new rule: Click on “Create Rule” and choose “Modify Headers” from the list of available rule types.
Add a new header modification:
- Under “Action”, select “Add” or “Override”.
- In the “Header Name” field, enter Permissions-Policy.
- In the “Header Value” field, enter your desired policy directives (e.g., geolocation=(), microphone=()).
Set the URL condition: Specify the URL or pattern where this header change should apply (e.g., https://your-website.com/*).
Save the rule.

Once configured, Requestly will inject the specified Permissions-Policy header into all matching requests, allowing you to test how enabling or disabling browser features affects your site’s behavior and security.