Permissions-Policy header

{{SeeCompatTable}}

The HTTP Permissions-Policy {{Glossary("response header")}} provides a mechanism to allow and deny the use of browser features in a document or within any {{HTMLElement("iframe")}} elements in the document.

For more information, see the main Permissions Policy article.

Syntax

Permissions-Policy: <directive>=<allowlist>

• <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 https://your-site.example.com. 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 {{HTMLElement('iframe','src','#Attributes')}} 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.

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

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

You can specify

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

[!NOTE] "https://*.example.com" does not match "https://example.com".

Directives

• {{httpheader('Permissions-Policy/accelerometer','accelerometer')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to gather information about the acceleration of the device through the {{DOMxRef("Accelerometer")}} interface.

• {{httpheader('Permissions-Policy/ambient-light-sensor','ambient-light-sensor')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to gather information about the amount of light in the environment around the device through the {{DOMxRef("AmbientLightSensor")}} interface.

• {{httpheader("Permissions-Policy/aria-notify", "aria-notify")}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the {{domxref("Document.ariaNotify", "ariaNotify()")}} method to fire {{glossary("screen reader")}} announcements.

• {{httpheader('Permissions-Policy/attribution-reporting','attribution-reporting')}} {{deprecated_inline}}

  • : Controls whether the current document is allowed to use the Attribution Reporting API.

• {{httpheader('Permissions-Policy/autoplay','autoplay')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to autoplay media requested through the {{domxref("HTMLMediaElement")}} interface. When this policy is disabled and there were no user gestures, the {{jsxref("Promise")}} returned by {{domxref("HTMLMediaElement.play()")}} will reject with a NotAllowedError {{domxref("DOMException")}}. The autoplay attribute on {{HTMLElement("audio")}} and {{HTMLElement("video")}} elements will be ignored.

• {{httpheader('Permissions-Policy/bluetooth','bluetooth')}} {{Experimental_Inline}}

  • : Controls whether the use of the Web Bluetooth API is allowed. When this policy is disabled, the methods of the {{DOMxRef("Bluetooth")}} object returned by {{DOMxRef("Navigator.bluetooth")}} will either return false or reject the returned {{JSxRef("Promise")}} with a SecurityError {{DOMxRef("DOMException")}}.

• {{httpheader('Permissions-Policy/browsing-topics','browsing-topics')}} {{deprecated_inline}} {{non-standard_inline}}

  • : Controls access to the Topics API. Where a policy specifically disallows the use of the Topics API, any attempts to call the {{domxref("Document.browsingTopics()")}} method or send a request with a {{httpheader("Sec-Browsing-Topics")}} header will fail with a NotAllowedError {{domxref("DOMException")}}.

• {{httpheader('Permissions-Policy/camera', 'camera')}} {{experimental_inline}}

  • : Controls whether the current document is allowed to use video input devices. The {{jsxref("Promise")}} returned by {{domxref("MediaDevices.getUserMedia", "getUserMedia()")}} will reject with a NotAllowedError {{DOMxRef("DOMException")}} if the permission is not allowed.

• {{HTTPHeader('Permissions-Policy/captured-surface-control', 'captured-surface-control')}} {{experimental_inline}}

  • : 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 {{DOMxRef("DOMException")}} if the permission is not allowed.

• {{HTTPHeader('Permissions-Policy/ch-ua-high-entropy-values', 'ch-ua-high-entropy-values')}} {{experimental_inline}}

  • : Controls whether or not the document is permitted to use the {{domxref("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.

• {{httpheader('Permissions-Policy/compute-pressure','compute-pressure')}} {{Experimental_Inline}}

  • : Controls access to the Compute Pressure API.

• {{httpheader('Permissions-Policy/cross-origin-isolated','cross-origin-isolated')}} {{Experimental_Inline}}

  • : Controls whether the current document can be treated as {{domxref("Window.crossOriginIsolated", "cross-origin isolated", "", 1)}}.

• {{HTTPHeader('Permissions-Policy/deferred-fetch', 'deferred-fetch')}} {{experimental_inline}}

  • : Controls the allocation of the top-level origin's fetchLater() quota.

• {{HTTPHeader('Permissions-Policy/deferred-fetch-minimal', 'deferred-fetch-minimal')}} {{experimental_inline}}

  • : Controls the allocation of the shared cross-origin subframe fetchLater() quota.

• {{HTTPHeader('Permissions-Policy/display-capture', 'display-capture')}} {{experimental_inline}}

  • : Controls whether or not the current document is permitted to use the {{domxref("MediaDevices.getDisplayMedia", "getDisplayMedia()")}} method to capture screen contents. When this policy is disabled, the promise returned by getDisplayMedia() will reject with a NotAllowedError {{DOMxRef("DOMException")}} if permission is not obtained to capture the display's contents.

• {{httpheader('Permissions-Policy/encrypted-media', 'encrypted-media')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the Encrypted Media Extensions API (EME). When this policy is disabled, the {{jsxref("Promise")}} returned by {{domxref("Navigator.requestMediaKeySystemAccess()")}} will reject with a SecurityError {{domxref("DOMException")}}.

• {{httpheader('Permissions-Policy/fullscreen','fullscreen')}} {{experimental_inline}}

  • : Controls whether the current document is allowed to use {{DOMxRef("Element.requestFullscreen()")}}. When this policy is disabled, the returned {{JSxRef("Promise")}} rejects with a {{JSxRef("TypeError")}}.

• {{httpheader('Permissions-Policy/gamepad','gamepad')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the Gamepad API. When this policy is disabled, calls to {{domxref('Navigator.getGamepads()')}} will throw a SecurityError {{domxref('DOMException')}}, and the {{domxref("Window.gamepadconnected_event", "gamepadconnected")}} and {{domxref("Window.gamepaddisconnected_event", "gamepaddisconnected")}} events will not fire.

• {{httpheader('Permissions-Policy/geolocation','geolocation')}} {{experimental_inline}}

  • : Controls whether the current document is allowed to use the {{domxref('Geolocation')}} Interface. When this policy is disabled, calls to {{domxref('Geolocation.getCurrentPosition','getCurrentPosition()')}} and {{domxref('Geolocation.watchPosition','watchPosition()')}} will cause those functions' callbacks to be invoked with a {{domxref('GeolocationPositionError')}} code of PERMISSION_DENIED.

• {{httpheader('Permissions-Policy/gyroscope','gyroscope')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to gather information about the orientation of the device through the {{DOMxRef("Gyroscope")}} interface.

• {{httpheader('Permissions-Policy/hid','hid')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the {{domxref("WebHID API", "WebHID API", "", "nocode")}} to connect to uncommon or exotic human interface devices such as alternative keyboards or gamepads.

• {{httpheader('Permissions-Policy/identity-credentials-get','identity-credentials-get')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the Federated Credential Management API (FedCM).

• {{httpheader('Permissions-Policy/idle-detection','idle-detection')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the {{domxref("Idle Detection API", "Idle Detection API", "", "nocode")}} to detect when users are interacting with their devices, for example to report "available"/"away" status in chat applications.

• {{httpheader("Permissions-Policy/language-detector", "language-detector")}} {{Experimental_Inline}}

  • : Controls access to the language detection functionality of the Translator and Language Detector APIs.

• {{httpheader('Permissions-Policy/local-fonts','local-fonts')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to gather data on the user's locally-installed fonts via the {{DOMxRef("Window.queryLocalFonts()")}} method (see also the {{domxref("Local Font Access API", "Local Font Access API", "", "nocode")}}).

• {{httpheader('Permissions-Policy/magnetometer','magnetometer')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to gather information about the orientation of the device through the {{DOMxRef("Magnetometer")}} interface.

• {{httpheader('Permissions-Policy/microphone','microphone')}} {{experimental_inline}}

  • : Controls whether the current document is allowed to use audio input devices. When this policy is disabled, the {{jsxref("Promise")}} returned by {{domxref("MediaDevices.getUserMedia()")}} will reject with a NotAllowedError {{domxref("DOMException")}}.

• {{httpheader('Permissions-Policy/midi', 'midi')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the Web MIDI API. When this policy is disabled, the {{jsxref("Promise")}} returned by {{domxref("Navigator.requestMIDIAccess()")}} will reject with a SecurityError {{domxref("DOMException")}}.

• {{httpheader("Permissions-Policy/on-device-speech-recognition", "on-device-speech-recognition")}} {{Experimental_Inline}}

  • : Controls access to the on-device speech recognition functionality of the Web Speech API.

• {{httpheader("Permissions-Policy/otp-credentials", "otp-credentials")}} {{Experimental_Inline}}

  • : 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 {{domxref("CredentialsContainer.get", "navigator.credentials.get({otp: ..., ...})")}}.

• {{httpheader('Permissions-Policy/payment', 'payment')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the Payment Request API. When this policy is enabled, the {{domxref("PaymentRequest","PaymentRequest()")}} constructor will throw a SecurityError {{domxref("DOMException")}}.

• {{httpheader('Permissions-Policy/picture-in-picture', 'picture-in-picture')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to play a video in a Picture-in-Picture mode via the corresponding API.

• {{httpheader('Permissions-Policy/private-state-token-issuance','private-state-token-issuance')}} {{Experimental_Inline}}

  • : Controls usage of private state token token-request operations.

• {{httpheader('Permissions-Policy/private-state-token-redemption','private-state-token-redemption')}} {{Experimental_Inline}}

  • : Controls usage of private state token token-redemption and send-redemption-record operations.

• {{httpheader("Permissions-Policy/publickey-credentials-create", "publickey-credentials-create")}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the Web Authentication API to create new asymmetric key credentials, i.e., via {{domxref("CredentialsContainer.create", "navigator.credentials.create({publicKey: ..., ...})")}}.

• {{httpheader("Permissions-Policy/publickey-credentials-get", "publickey-credentials-get")}} {{experimental_inline}}

  • : Controls whether the current document is allowed to use the Web Authentication API to retrieve already stored public-key credentials, i.e., via {{domxref("CredentialsContainer.get", "navigator.credentials.get({publicKey: ..., ...})")}}.

• {{httpheader('Permissions-Policy/screen-wake-lock', 'screen-wake-lock')}} {{experimental_inline}}

  • : 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.

• {{httpheader('Permissions-Policy/serial','serial')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the {{domxref("Web Serial API", "Web Serial API", "", "nocode")}} to communicate with serial devices, either directly connected via a serial port, or via USB or Bluetooth devices emulating a serial port.

• {{httpheader("Permissions-Policy/speaker-selection", "speaker-selection")}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the Audio Output Devices API to list and select speakers.

• {{httpheader("Permissions-Policy/storage-access", "storage-access")}} {{Experimental_Inline}}

  • : Controls whether a document loaded in a third-party context (i.e., embedded in an {{htmlelement("iframe")}}) is allowed to use the {{domxref("Storage Access API", "Storage Access API", "", "nocode")}} to request access to unpartitioned cookies.

• {{httpheader("Permissions-Policy/translator", "translator")}} {{Experimental_Inline}}

  • : Controls access to the translation functionality of the Translator and Language Detector APIs.

• {{httpheader("Permissions-Policy/summarizer", "summarizer")}} {{Experimental_Inline}}

  • : Controls access to the Summarizer API.

• {{httpheader('Permissions-Policy/usb', 'usb')}} {{Experimental_Inline}}

  • : Controls whether the current document is allowed to use the WebUSB API.

• {{httpheader("Permissions-Policy/web-share", "web-share")}} {{experimental_inline}}

  • : Controls whether or not the current document is allowed to use the {{domxref("Navigator.share","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.

• {{httpheader("Permissions-Policy/window-management", "window-management")}} {{experimental_inline}}

  • : Controls whether or not the current document is allowed to use the Window Management API to manage windows on multiple displays.

• {{httpheader("Permissions-Policy/xr-spatial-tracking", "xr-spatial-tracking")}} {{Experimental_Inline}}

  • : 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:

Permissions-Policy: geolocation=*

Or to allow access to a subset of origins, you'd do this:

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:

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:

<iframe src="https://example.com" allow="geolocation *"></iframe>

To apply a policy to the current origin and others, you'd do this:

<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com"></iframe>

This is important: By default, if an <iframe> 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.

<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com; fullscreen 'none'"></iframe>

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 <iframe>, as long as the document loaded into it comes from the same origin as the URL in its {{HTMLElement('iframe','src','#Attributes')}} attribute. This value is the default allowlist value for features listed in allow, so the following are equivalent:

<iframe src="https://example.com" allow="geolocation 'src'"></iframe>
<iframe src="https://example.com" allow="geolocation"></iframe>

Denying access to powerful features

SecureCorp Inc. wants to disable Microphone (for example {{domxref("MediaDevices.getUserMedia()")}}) and {{domxref("Geolocation")}} APIs in its application. It can do so using the following response header:

Permissions-Policy: microphone=(), geolocation=()

By specifying () for the origin list, the specified features will be disabled for all browsing contexts (this includes all <iframe>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:

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

Over in our ad <iframe>s, we could set access to the https://trusted-ad-network.com origin like this:

<iframe src="https://trusted-ad-network.com" allow="geolocation"></iframe>

If a different origin ended up getting loaded into <iframe>, it would not have access to geolocation:

<iframe src="https://rogue-origin-example.com" allow="geolocation"></iframe>

Specifications

{{Specifications}}

Browser compatibility

{{Compat}}

See also

• Permissions Policy
• {{DOMxRef("Document.featurePolicy")}} and {{DOMxRef("FeaturePolicy")}}
• {{HTTPHeader("Content-Security-Policy")}}
• {{HTTPHeader("Referrer-Policy")}}