Permissions-Policy header - HTTP

Permissions-Policy header - HTTP | MDN
Skip to search
Permissions-Policy header
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
See full compatibility
Report feedback
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. Violations of a policy can be reported using the Reporting API Reports may be sent to a server indicated by name in a per-directive report-to parameter, or otherwise to the server endpoint named "default" (the mapping between server endpoint names and URLs is set using the Reporting-Endpoints HTTP response header). Reports can also be observed in the page for which the policy is being enforced using a ReportingObserver The format of the report and additional detail is provided in PermissionsPolicyViolationReport For more information, see the main Permissions Policy article. Header type Response header Syntax http # Single directive Permissions-Policy: <directive>=<allowlist> # Single directive with reporting endpoint Permissions-Policy: <directive>=<allowlist>;report-to=<endpoint> # Multiple directives, with and without server reporting endpoints Permissions-Policy: <directive>=<allowlist>, <directive>=<allowlist>;report-to=<endpoint>, ... The header can be used to set the allowlists for one or more directives, and optionally a per-directive report-to parameter indicating the server endpoint to send policy violation reports to. The entries for each directive are comma separated. <directive> The Permissions Policy directive to apply the allowlist to. See Directives below for a list of the permitted directive names. <allowlist> 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 allowed in this document, and all nested browsing contexts ( <iframe> s) regardless of their origin. () (empty allowlist) The feature is disabled in top-level and nested browsing contexts. The equivalent for <iframe> allow attributes is 'none' self The feature will be allowed in this document, and in all nested browsing contexts ( <iframe> s) in the same origin only. The feature is not allowed in cross-origin documents in nested browsing contexts. self can be considered shorthand for . The equivalent for <iframe> allow attributes is self src The feature will be allowed in this <iframe> , as long as the document loaded into it comes from the same origin as the URL in its src attribute. This value is only used in the <iframe> allow attribute, and is the default allowlist value in <iframe> s. "<origin>" The feature is allowed for specific origins (for example, "https://a.example.com" ). Origins should be separated by spaces. Note that origins in <iframe> allow attributes are not quoted. The values and () may only be used on their own, while self and src may be used in combination with one or more origins. Note: Directives have a default allowlist, which is always one of self , or none for the Permissions-Policy HTTP header, and governs the default behavior if they are not explicitly listed in a policy. These are specified on the individual directive reference pages . For <iframe> allow attributes, the default behavior is always src report-to=<endpoint> Optional The report-to parameter can be used to indicate the name of a reporting endpoint where reports will be sent if there is a policy violation for the associated directive. The endpoint name and its associated URL must be specified in a separate Reporting-Endpoints HTTP response header. If omitted, reports will be send to the default reporting endpoint if one has been defined. See Reporting API for more information. Where supported, you can include wildcards in Permissions Policy origins. This means that instead of having to explicitly specify several different subdomains in an allowlist, you can specify them all in a single origin with a wildcard. So instead of: http ("https://example.com" "https://a.example.com" "https://b.example.com" "https://c.example.com") You can specify: http ("https://example.com" "https://*.example.com") Note: "https://*.example.com" does not match "https://example.com" Directives accelerometer Experimental Controls whether the current document is allowed to gather information about the acceleration of the device through the Accelerometer interface. ambient-light-sensor Experimental Controls whether the current document is allowed to gather information about the amount of light in the environment around the device through the AmbientLightSensor interface. aria-notify Experimental Controls whether the current document is allowed to use the ariaNotify() method to fire screen reader announcements. attribution-reporting Deprecated Controls whether the current document is allowed to use the Attribution Reporting API autoplay Experimental Controls whether the current document is allowed to autoplay media requested through the HTMLMediaElement interface. When this policy is disabled and there were no user gestures, the Promise returned by HTMLMediaElement.play() will reject with a NotAllowedError DOMException . The autoplay attribute on <audio> and <video> elements will be ignored. bluetooth Experimental Controls whether the use of the Web Bluetooth API is allowed. When this policy is disabled, the methods of the Bluetooth object returned by Navigator.bluetooth will either return false or reject the returned Promise with a SecurityError DOMException browsing-topics Deprecated Non-standard Controls access to the Topics API . Where a policy specifically disallows the use of the Topics API, any attempts to call the Document.browsingTopics() method or send a request with a Sec-Browsing-Topics header will fail with a NotAllowedError DOMException camera Experimental Controls whether the current document is allowed to use video input devices. The Promise returned by getUserMedia() will reject with a NotAllowedError DOMException if the permission is not allowed. captured-surface-control Experimental Controls whether or not the document is permitted to use the Captured Surface Control API The promise returned by the API's main methods will reject with a NotAllowedError DOMException if the permission is not allowed. ch-ua-high-entropy-values Experimental Controls whether or not the document is permitted to use the NavigatorUAData.getHighEntropyValues() method to retrieve high-entropy user-agent data. If the permission is not allowed, the method will only return the brands mobile , and platform low-entropy data. compute-pressure Experimental Controls access to the Compute Pressure API cross-origin-isolated Experimental Controls whether the current document can be treated as cross-origin isolated deferred-fetch Experimental Controls the allocation of the top-level origin's fetchLater() quota deferred-fetch-minimal Experimental Controls the allocation of the shared cross-origin subframe fetchLater() quota display-capture Experimental Controls whether or not the current document is permitted to use the getDisplayMedia() method to capture screen contents. When this policy is disabled, the promise returned by getDisplayMedia() will reject with a NotAllowedError DOMException if permission is not obtained to capture the display's contents. encrypted-media Experimental Controls whether the current document is allowed to use the Encrypted Media Extensions API (EME). When this policy is disabled, the Promise returned by Navigator.requestMediaKeySystemAccess() will reject with a SecurityError DOMException fullscreen Experimental Controls whether the current document is allowed to use Element.requestFullscreen() . When this policy is disabled, the returned Promise rejects with a TypeError gamepad Experimental Controls whether the current document is allowed to use the Gamepad API When this policy is disabled, calls to Navigator.getGamepads() will throw a SecurityError DOMException , and the gamepadconnected and gamepaddisconnected events will not fire. geolocation Experimental Controls whether the current document is allowed to use the Geolocation Interface. When this policy is disabled, calls to getCurrentPosition() and watchPosition() will cause those functions' callbacks to be invoked with a GeolocationPositionError code of PERMISSION_DENIED gyroscope Experimental Controls whether the current document is allowed to gather information about the orientation of the device through the Gyroscope interface. hid Experimental Controls whether the current document is allowed to use the WebHID API to connect to uncommon or exotic human interface devices such as alternative keyboards or gamepads. identity-credentials-get Experimental Controls whether the current document is allowed to use the Federated Credential Management API (FedCM) idle-detection Experimental Controls whether the current document is allowed to use the Idle Detection API to detect when users are interacting with their devices, for example to report "available"/"away" status in chat applications. language-detector Experimental Controls access to the language detection functionality of the Translator and Language Detector APIs local-fonts Experimental Controls whether the current document is allowed to gather data on the user's locally-installed fonts via the Window.queryLocalFonts() method (see also the Local Font Access API ). magnetometer Experimental Controls whether the current document is allowed to gather information about the orientation of the device through the Magnetometer interface. microphone Experimental Controls whether the current document is allowed to use audio input devices. When this policy is disabled, the Promise returned by MediaDevices.getUserMedia() will reject with a NotAllowedError DOMException midi Experimental Controls whether the current document is allowed to use the Web MIDI API . When this policy is disabled, the Promise returned by Navigator.requestMIDIAccess() will reject with a SecurityError DOMException on-device-speech-recognition Experimental Controls access to the on-device speech recognition functionality of the Web Speech API otp-credentials Experimental Controls whether the current document is allowed to use the WebOTP API to request a one-time password (OTP) from a specially-formatted SMS message sent by the app's server, i.e., via navigator.credentials.get({otp: ..., ...}) payment Experimental Controls whether the current document is allowed to use the Payment Request API . When this policy is enabled, the PaymentRequest() constructor will throw a SecurityError DOMException picture-in-picture Experimental Controls whether the current document is allowed to play a video in a Picture-in-Picture mode via the corresponding API. private-state-token-issuance Experimental Controls usage of private state token token-request operations. private-state-token-redemption Experimental Controls usage of private state token token-redemption and send-redemption-record operations. publickey-credentials-create Experimental Controls whether the current document is allowed to use the Web Authentication API to create new asymmetric key credentials, i.e., via navigator.credentials.create({publicKey: ..., ...}) publickey-credentials-get Experimental Controls whether the current document is allowed to use the Web Authentication API to retrieve already stored public-key credentials, i.e., via navigator.credentials.get({publicKey: ..., ...}) screen-wake-lock Experimental Controls whether the current document is allowed to use Screen Wake Lock API to indicate that device should not turn off or dim the screen. serial Experimental Controls whether the current document is allowed to use the Web Serial API to communicate with serial devices, either directly connected via a serial port, or via USB or Bluetooth devices emulating a serial port. speaker-selection Experimental Controls whether the current document is allowed to use the Audio Output Devices API to list and select speakers. storage-access Experimental Controls whether a document loaded in a third-party context (i.e., embedded in an <iframe> ) is allowed to use the Storage Access API to request access to unpartitioned cookies. translator Experimental Controls access to the translation functionality of the Translator and Language Detector APIs summarizer Experimental Controls access to the Summarizer API usb Experimental Controls whether the current document is allowed to use the WebUSB API web-share Experimental Controls whether or not the current document is allowed to use the Navigator.share() of Web Share API to share text, links, images, and other content to arbitrary destinations of user's choice, e.g., mobile apps. window-management Experimental Controls whether or not the current document is allowed to use the Window Management API to manage windows on multiple displays. xr-spatial-tracking Experimental Controls whether or not the current document is allowed to use the WebXR Device API to interact with a WebXR session. Examples Basic usage Permissions-Policy header To allow all origins access to geolocation, you would do this: http Permissions-Policy: geolocation=* Or to allow access to a subset of origins, you'd do this: http Permissions-Policy: geolocation=(self "https://a.example.com" "https://b.example.com") Several features can be controlled at the same time by sending the header with a comma-separated list of policies, or by sending a separate header for each policy. For example, the following are equivalent: http Permissions-Policy: picture-in-picture=(), geolocation=(self https://example.com/), camera=* Permissions-Policy: picture-in-picture=() Permissions-Policy: geolocation=(self https://example.com/) Permissions-Policy: camera=* iframes For an <iframe> to have a feature enabled its allowed origin must also be in the allowlist for the parent page. Because of this inheritance behavior , it is a good idea to specify the widest acceptable support for a feature in the HTTP header, and then specify the subset of support you need in each <iframe> To allow all origins access to geolocation, you would do this: html <iframe src="https://example.com" allow="geolocation *">
To apply a policy to the current origin and others, you'd do this:
html
src="https://example.com"
allow="geolocation 'self' https://a.example.com https://b.example.com">
This is important: By default, if an
 navigates to another origin, the policy is not applied to the origin that the <iframe> navigates to. By listing the origin that the <iframe> navigates to in the allow attribute, the Permissions Policy that was applied to the original <iframe> will be applied to the origin the <iframe> navigates to. Several features can be controlled at the same time by including a semi-colon-separated list of policy directives inside the allow attribute. html <iframe src="https://example.com" allow="geolocation 'self' https://a.example.com https://b.example.com; fullscreen 'none'">
It is worth giving the
src
value a special mention. We mentioned above that using this allowlist value will mean that the associated feature will be allowed in this
 , as long as the document loaded into it comes from the same origin as the URL in its src attribute. This value is the default allowlist value for features listed in allow , so the following are equivalent: html <iframe src="https://example.com" allow="geolocation 'src'">

Denying access to powerful features
SecureCorp Inc. wants to disable Microphone (for example
MediaDevices.getUserMedia()
) and
Geolocation
APIs in its application. It can do so using the following response header:
http
Permissions-Policy: microphone=(), geolocation=()
By specifying
()
for the origin list, the specified features will be disabled for all browsing contexts (this includes all
 s), regardless of their origin. Combining HTTP header and <iframe> policies For example, let's say that we wanted to enable geolocation usage on our own origin, and in embedded content coming from our trusted ad network. We could set up the page-wide Permissions Policy like this: http Permissions-Policy: geolocation=(self https://trusted-ad-network.com) Over in our ad <iframe> s, we could set access to the origin like this: html <iframe src="https://trusted-ad-network.com" allow="geolocation">
If a different origin ended up getting loaded into
 , it would not have access to geolocation: html <iframe src="https://rogue-origin-example.com" allow="geolocation">
Reporting violations
This example shows how to configure reporting of
Permissions-Policy
violations to a server endpoint.
The response headers below block geolocation and define the reporting endpoint name for the feature as "geo_endpoint".
The
Reporting-Endpoints
HTTP response header is used to define the URL of this endpoint name.
http
Reporting-Endpoints: geo_endpoint="https://example.com/reports"
Permissions-Policy: geolocation=();report-to=geo_endpoint
Note:
To send all violation reports to the same endpoint we might instead define the
"default"
reporting endpoint
http
Reporting-Endpoints: default="https://example.com/reports"
Permissions-Policy: geolocation=()
A violation occurs when a page attempts to use the blocked feature, for example:
js
navigator.geolocation.getCurrentPosition(
() => {},
() => {},
);
The
report payload
sent to the endpoint might look like this:
json
"age": 48512,
"body": {
"columnNumber": 29,
"disposition": "enforce",
"lineNumber": 44,
"message": "Permissions policy violation: geolocation access has been blocked because of a permissions policy applied to the current document.",
"featureId": "geolocation",
"sourceFile": "https://example.com/"
},
"type": "permissions-policy-violation",
"url": "https://example.com/",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36"
Note:
Chrome's server-side serialization of violation reports uses
policyId
rather than
featureId
for the feature name in the
body
of a server report.
The
PermissionsPolicyViolationReport
returned by a
ReportingObserver
follows the specification.
Specifications
Specification
Permissions Policy
# permissions-policy-http-header-field
Browser compatibility
See also
Permissions Policy
Permissions-Policy-Report-Only
Document.featurePolicy
and
FeaturePolicy
Content-Security-Policy
Referrer-Policy
Reporting-Endpoints
PermissionsPolicyViolationReport
ReportingObserver
Reporting API
Help improve MDN
Learn how to contribute
This page was last modified on
Apr 21, 2026
by
MDN contributors
View this page on GitHub
Report a problem with this content