The HTTPPermissions-Policyresponse header provides a mechanism to allow and deny the use of browser features in a document or within any<iframe> elements in the document.

For more information, see the mainPermissions Policy article.

Syntax

Permissions-Policy: <directive>=<allowlist>

<directive>

The Permissions Policy directive to apply theallowlist to. SeeDirectives 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 forhttps://your-site.example.com. The equivalent for<iframe>allow attributes isself.

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 itssrc attribute. This value is only used in the<iframe>allow attribute, and is thedefaultallowlist 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, whileself andsrc may be used in combination with one or more origins.

Note:Directives have a default allowlist, which is always one of*,self, ornone for thePermissions-Policy HTTP header, and governs the default behavior if they are not explicitly listed in a policy.These are specified on the individualdirective reference pages. For<iframe>allow attributes, the default behavior is alwayssrc.

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")

Directives

accelerometerExperimental

Controls whether the current document is allowed to gather information about the acceleration of the device through theAccelerometer interface.

ambient-light-sensorExperimental

Controls whether the current document is allowed to gather information about the amount of light in the environment around the device through theAmbientLightSensor interface.

aria-notifyExperimentalNon-standard

Controls whether the current document is allowed to use theariaNotify() method to firescreen reader announcements.

attribution-reportingExperimental

Controls whether the current document is allowed to use theAttribution Reporting API.

autoplayExperimental

Controls whether the current document is allowed to autoplay media requested through theHTMLMediaElement interface. When this policy is disabled and there were no user gestures, thePromise returned byHTMLMediaElement.play() will reject with aNotAllowedErrorDOMException. The autoplay attribute on<audio> and<video> elements will be ignored.

bluetoothExperimental

Controls whether the use of theWeb Bluetooth API is allowed. When this policy is disabled, the methods of theBluetooth object returned byNavigator.bluetooth will either returnfalse or reject the returnedPromise with aSecurityErrorDOMException.

browsing-topicsExperimentalNon-standard

Controls access to theTopics API. Where a policy specifically disallows the use of the Topics API, any attempts to call theDocument.browsingTopics() method or send a request with aSec-Browsing-Topics header will fail with aNotAllowedErrorDOMException.

cameraExperimental

Controls whether the current document is allowed to use video input devices.ThePromise returned bygetUserMedia() will reject with aNotAllowedErrorDOMException if the permission is not allowed.

captured-surface-controlExperimental

Controls whether or not the document is permitted to use theCaptured Surface Control API.The promise returned by the API's main methods will reject with aNotAllowedErrorDOMException if the permission is not allowed.

compute-pressureExperimental

Controls access to theCompute Pressure API.

cross-origin-isolatedExperimental

Controls whether the current document can be treated ascross-origin isolated.

deferred-fetchExperimental

Controls the allocation of the top-level origin'sfetchLater() quota.

deferred-fetch-minimalExperimental

Controls the allocation of the shared cross-origin subframefetchLater() quota.

display-captureExperimental

Controls whether or not the current document is permitted to use thegetDisplayMedia() method to capture screen contents. When this policy is disabled, the promise returned bygetDisplayMedia() will reject with aNotAllowedErrorDOMException if permission is not obtained to capture the display's contents.

encrypted-mediaExperimental

Controls whether the current document is allowed to use theEncrypted Media Extensions API (EME). When this policy is disabled, thePromise returned byNavigator.requestMediaKeySystemAccess() will reject with aSecurityErrorDOMException.

fullscreenExperimental

Controls whether the current document is allowed to useElement.requestFullscreen(). When this policy is disabled, the returnedPromise rejects with aTypeError.

gamepadExperimental

Controls whether the current document is allowed to use theGamepad API.When this policy is disabled, calls toNavigator.getGamepads() will throw aSecurityErrorDOMException, and thegamepadconnected andgamepaddisconnected events will not fire.

geolocationExperimental

Controls whether the current document is allowed to use theGeolocation Interface. When this policy is disabled, calls togetCurrentPosition() andwatchPosition() will cause those functions' callbacks to be invoked with aGeolocationPositionError code ofPERMISSION_DENIED.

gyroscopeExperimental

Controls whether the current document is allowed to gather information about the orientation of the device through theGyroscope interface.

hidExperimental

Controls whether the current document is allowed to use theWebHID API to connect to uncommon or exotic human interface devices such as alternative keyboards or gamepads.

identity-credentials-getExperimental

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

idle-detectionExperimental

Controls whether the current document is allowed to use theIdle Detection API to detect when users are interacting with their devices, for example to report "available"/"away" status in chat applications.

language-detectorExperimental

Controls access to the language detection functionality of theTranslator and Language Detector APIs.

local-fontsExperimental

Controls whether the current document is allowed to gather data on the user's locally-installed fonts via theWindow.queryLocalFonts() method (see also theLocal Font Access API).

magnetometerExperimental

Controls whether the current document is allowed to gather information about the orientation of the device through theMagnetometer interface.

microphoneExperimental

Controls whether the current document is allowed to use audio input devices. When this policy is disabled, thePromise returned byMediaDevices.getUserMedia() will reject with aNotAllowedErrorDOMException.

midiExperimental

Controls whether the current document is allowed to use theWeb MIDI API. When this policy is disabled, thePromise returned byNavigator.requestMIDIAccess() will reject with aSecurityErrorDOMException.

on-device-speech-recognitionExperimental

Controls access to theon-device speech recognition functionality of theWeb Speech API.

otp-credentialsExperimental

Controls whether the current document is allowed to use theWebOTP API to request a one-time password (OTP) from a specially-formatted SMS message sent by the app's server, i.e., vianavigator.credentials.get({otp: ..., ...}).

paymentExperimental

Controls whether the current document is allowed to use thePayment Request API. When this policy is enabled, thePaymentRequest() constructor will throw aSecurityErrorDOMException.

picture-in-pictureExperimental

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

publickey-credentials-createExperimental

Controls whether the current document is allowed to use theWeb Authentication API to create new asymmetric key credentials, i.e., vianavigator.credentials.create({publicKey: ..., ...}).

publickey-credentials-getExperimental

Controls whether the current document is allowed to use theWeb Authentication API to retrieve already stored public-key credentials, i.e., vianavigator.credentials.get({publicKey: ..., ...}).

screen-wake-lockExperimental

Controls whether the current document is allowed to useScreen Wake Lock API to indicate that device should not turn off or dim the screen.

serialExperimental

Controls whether the current document is allowed to use theWeb 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-selectionExperimental

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

storage-accessExperimental

Controls whether a document loaded in a third-party context (i.e., embedded in an<iframe>) is allowed to use theStorage Access API to request access to unpartitioned cookies.

translatorExperimental

Controls access to the translation functionality of theTranslator and Language Detector APIs.

summarizerExperimental

Controls access to theSummarizer API.

usbExperimental

Controls whether the current document is allowed to use theWebUSB API.

web-shareExperimental

Controls whether or not the current document is allowed to use theNavigator.share() ofWeb Share API to share text, links, images, and other content to arbitrary destinations of user's choice, e.g., mobile apps.

window-managementExperimental

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

xr-spatial-trackingExperimental

Controls whether or not the current document is allowed to use theWebXR 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 thisinheritance 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 theallow 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 theallow attribute.

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

It is worth giving thesrc 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 itssrc attribute. This value is thedefaultallowlist value for features listed inallow, 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 exampleMediaDevices.getUserMedia()) andGeolocation 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 thehttps://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

Browser compatibility

See also

• Permissions Policy
• Document.featurePolicy andFeaturePolicy
• Content-Security-Policy
• Referrer-Policy