Abstract

This specification defines common infrastructure that other specifications can use to interact with browser permissions. These permissions represent a user's choice to allow or deny access to "powerful features" of the platform. For developers, the specification standardizes an API to query the permission state of a powerful feature, and be notified if a permission to use a powerful feature changes state.

Status of This Document

This section describes the status of this document at the time of its publication. A list of currentW3C publications and the latest revision of this technical report can be found in theW3C standards and drafts index.

This is a work in progress.

This document was published by theWeb Application Security Working Group as an Editor's Draft.

Publication as an Editor's Draft does not imply endorsement byW3C and its Members.

This is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite this document as other than a work in progress.

This document was produced by a group operating under theW3C Patent Policy.W3C maintains apublic list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent that the individual believes containsEssential Claim(s) must disclose the information in accordance withsection 6 of theW3C Patent Policy.

This document is governed by the18 August 2025W3C Process Document.

This section is non-normative.

Specifications can define features that are explicitly identified as apowerful feature. These features are said to be "powerful" in that they can have significant privacy, security, and performance implications. As such, users rely on user agents to deny sites the ability to use these features until they have given express permission, and usually only granting this ability for a limited amount of time. Express permission to allow a site to use a powerful feature is generally given and controlled through browser UI, as illustrated below.

In this sense, a permission represents the current state of user consent for certain types of features, and particularly "powerful features". Ultimately the user retains control of these permissions and have the ability to manually grant or deny permissions through user preferences. Further, user agents assist users in managing permissions by, for example, hiding and automatically denying certain permission prompts that would otherwise be a nuisance, and automatically expiring granted permissions if a user doesn't visit a website for some time.

This section is non-normative.

This example uses the Permissions API to decide whether local news should be shown using the Geolocation API or with a button offering to add the feature.

const { state } =await navigator.permissions.query({name:"geolocation"});switch (state) {case"granted":showLocalNewsWithGeolocation();break;case"prompt":showButtonToEnableLocalNews();break;case"denied":showNationalNews();break;}

This example simultaneously checks the state of the"geolocation" and"notifications"powerful features:

const queryPromises = ["geolocation","notifications"].map(name => navigator.permissions.query({ name }));forawait (const statusof queryPromises) {console.log(`${status.name}:${status.state}`);}

This example is checking the permission state of the available cameras.

const devices =await navigator.mediaDevices.enumerateDevices();// filter on video inputs, and map to query objectconst queries = devices  .filter(({ kind }) => kind ==="videoinput")  .map(({ deviceId }) => ({name:"camera", deviceId }));const promises = queries.map((queryObj) =>  navigator.permissions.query(queryObj));try {const results =awaitPromise.all(promises);// log the state of each camera  results.forEach(({ state }, i) =>console.log("Camera", i, state));}catch (error) {console.error(error);}

This section specifies a model forpermissions to usepowerful features on the Web platform.

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

dictionary SensesPermissionDescriptor :PermissionDescriptor {booleancanSmell=false;booleancanTaste=false;};

// Check if the "senses" powerful feature is allowed to smell thingsconst status =await navigator.permissions.query({name:"senses",canSmell:true,});// Do something interesting with the status.

When a conformingspecificationspecifies a powerful feature it:

1. MUST give thepowerful feature aname in the form of aascii lowercase string.
2. MAY define apermission descriptor type that inherits fromPermissionDescriptor.
3. MAY define zero or moreaspects.
4. MAY override the algorithms and types given below if the defaults are not suitable for a particularpowerful feature.
5. MUST register thepowerful feature in thePermissions Registry.

Registering the newly specifiedpowerful features in thePermissions Registry gives this Working Group an opportunity to provide feedback and check that integration with this specification is done effectively.

Apermission descriptor type:

PermissionDescriptor or one of its subtypes. If unspecified, this defaults toPermissionDescriptor.

The feature can define apartial order on descriptor instances. IfdescriptorA isstronger thandescriptorB, then ifdescriptorA'spermission state is "granted",descriptorB'spermission state must also be "granted", and ifdescriptorB'spermission state is "denied",descriptorA'spermission state must also be "denied".

Example 6: A permission descriptor that defines a partial order

{name: "midi", sysex: true} ("midi-with-sysex") isstronger than{name: "midi", sysex: false} ("midi-without-sysex"), so if the user denies access to midi-without-sysex, the UA must also deny access to midi-with-sysex, and similarly if the user grants access to midi-with-sysex, the user agent must also grant access to midi-without-sysex.

permission state constraints:

Constraints on the values that the user agent can return as a descriptor'spermission state. Defaults to no constraints beyond the user's intent.

extra permission data type:

Somepowerful features have more information associated with them than just aPermissionState. Each of these features defines anextra permission data type.

Note

For example,getUserMedia() needs to determinewhich cameras the user has granted permission to access.

If aDOMStringname names one of these features, thenname'sextra permission data for an optionalenvironment settings objectsettings is the result of the following algorithm:

1. Ifsettings wasn't passed, set it to thecurrent settings object.
2. If there was a previous invocation of this algorithm with the samename andsettings, returningpreviousResult, and the user agent has not receivednew information about the user's intent since that invocation, returnpreviousResult.
3. Return the instance ofname'sextra permission data type that matches the UA's impression of the user's intent, taking into account anyextra permission data constraints forname.

If specified, theextra permission data algorithm is usable for this feature.

Optionalextra permission data constraints:

Constraints on the values that the user agent can return as apowerful feature'sextra permission data. Defaults to no constraints beyond the user's intent.

Apermission result type:

PermissionStatus or one of its subtypes. If unspecified, this defaults toPermissionStatus.

Apermission query algorithm:

Takes an instance of thepermission descriptor type and a new or existing instance of thepermission result type, and updates thepermission result type instance with the query result. Used byPermissions'query(permissionDesc) method and thePermissionStatus update steps. If unspecified, this defaults to thedefault permission query algorithm.

Thedefault permission query algorithm, given aPermissionDescriptorpermissionDesc and aPermissionStatusstatus, runs the following steps:

1. Setstatus'sstate topermissionDesc's permission state.

Apermission key type:

The type ofpermission key used by the feature. Defaults toorigin. A feature that specifies a custompermission key typeMUST also specify apermission key generation algorithm.

Apermission key generation algorithm:

Takes anoriginorigin and anoriginembedded origin, and returns a newpermission key. If unspecified, this defaults to thedefault permission key generation algorithm. A feature that specifies a custompermission key generation algorithmMUST also specify apermission key comparison algorithm.

Thedefault permission key generation algorithm, given anoriginorigin and anoriginembedded origin, runs the following steps:

1. Returnorigin.

Note: Permission Delegation

Most powerful features grant permission to the top-level origin and delegate access to the requesting document viaPermissions Policy. This is known as permission delegation.

Apermission key comparison algorithm:

Takes twopermission keys and returns aboolean that shows whether the two keys are equal. If unspecified, this defaults to thedefault permission key comparison algorithm.

Thedefault permission key comparison algorithm, givenpermission keyskey1 andkey2, runs the following steps:

1. Returnkey1 issame origin withkey2.

Apermission revocation algorithm:

Takes no arguments. Updates any other parts of the implementation that need to be kept in sync with changes in the results ofpermission states orextra permission data.

If unspecified, this defaults to runningreact to the user revoking permission.

A permissionlifetime:

Specifications that define one or morepowerful featuresSHOULD suggest apermissionlifetime that is best suited for the particular feature. Some guidance on determining the lifetime of a permission is noted below, with a strong emphasis on user privacy. If nolifetime is specified, the user agent provides one.

When the permissionlifetime expires for an origin:

1. Set the permission back to its defaultpermission state (e.g., by setting it back to"prompt").
2. For eachbrowsing context associated with the origin (if any),queue a global task on thepermissions task source with thebrowsing context'sglobal object to run thepermission revocation algorithm.

Note: Determining the lifetime of a permission

For particularly privacy-sensitivefeatures, such asMedia Capture and Streams, which can provide a web application access to a user's camera and microphone, some user agents expire a permissiongrant as soon as a browser tab is closed ornavigated. For other features, like theGeolocation, user agents are known to offer a choice of only granting the permission for the session, or for one day. Others, like theNotifications API Standard andPush API APIs, remember a user's decision indefinitely or until the user manually revokes the permission. Note that permissionlifetimes can vary significantly between user agents.

Finding the right balance for the lifetime of a permission requires a lot of thought and experimentation, and often evolves over a period of years. Implementers are encouraged to work with their UX security teams to find the right balance between ease of access to apowerful feature (i.e., reducing the number of permission prompts), respecting a user's privacy, and making users aware when a web application is making use of a particular powerful feature (e.g., via some visual or auditory UI indicator).

If you are unsure about whatlifetime to suggest for apowerful feature, please contact thePrivacy Interest Group for guidance.

Default permission state:

AnPermissionState value that serves as apermission'sdefault state of apowerful feature.

If not specified, thepermission'sdefault state is "prompt".

Adefault powerful feature is apowerful feature with all of the above types and algorithms defaulted.

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key wordsMAY,MUST,MUST NOT,OPTIONAL, andSHOULD in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Two classes of product can claim conformance to this specification:user agents and otherspecifications (i.e., a technical report thatspecifies a powerful feature in a manner that conforms to the requirements of this specification).

This section is non-normative.

Although both this specification and thePermissions Policy specification deal with "permissions", each specification serves a distinct purpose in the platform. Nevertheless, the two specifications do explicitly overlap.

On the one hand, this specification exclusively concerns itself withpowerful features whose access is managed through a user-agent mediated permissions UI (i.e., permissions where the user gives express consent before that feature can be used, and where the user retains the ability to deny that permission at any time for any reason). These powerful features are registered in thePermissions Registry.

On the other hand, thePermissions Policy specification allows developers to selectively enable and disable policy-controlled features through a "permissions policy" (be it a HTTP header or theallow attribute). In that sense, the Permissions Policy subsumes this specification in thatPermissions Policy governs whether a feature is available at all, independently of this specification. These policy-controlled features are also registered in thePermissions Registry.

A powerful feature that has been disabled by thePermissions Policy specification always has itspermission state reflected as "denied" by this specification. This occurs becausereading the current permission relies on [HTML]'s "allowed to use" check, which itself calls into thePermissions Policy specification. Important to note here is the sharing of permission names across both specifications. Both this specification and thePermissions Policy specification rely on other specifications defining the names of the permission andname, and they are usually named the same thing (e.g., "geolocation" of theGeolocation, and so on).

Finally, it's not possible for a powerful feature to ever become "granted" through any means provided by thePermissions Policy specification. The only way that apowerful feature can be"granted" is by the user givingexpress permission or by some user agent policy.

For the purposes of user-agent automation and application testing, this document defines extensions to the [WebDriver] and [WebDriver-BiDi] specifications. It isOPTIONAL for a user agent to support them.

WebIDLdictionaryPermissionSetParameters {  requiredobjectdescriptor;  requiredPermissionStatestate;};

{"descriptor":{"name":"midi","sysex":true},"state":"granted"}

PermissionsCommand = (  permissions.setPermission)

permissions.PermissionDescriptor = {  name: text,}

permissions.PermissionState = "granted" / "denied" / "prompt"

This section is non-normative.

An adversary could use apermission state as an element in creating a "fingerprint" corresponding to an end-user. Although an adversary can already determine the state of a permission by actually using the API, that often leads to a UI prompt being presented to the end-user (if the permission was not already"granted"). Even though this API doesn't expose new fingerprinting information to websites, it makes it easier for an adversary to have discreet access to this information.

A user agentSHOULD provide a means for the user to review, update, and reset thepermissionstate ofpowerful features associated with anorigin.

There are no documented security considerations at this time. Readers are instead encouraged to read sectionD. Privacy considerations.

WebIDL[Exposed=(Window)]partial interfaceNavigator {  [SameObject] readonly attributePermissionspermissions;};[Exposed=(Worker)]partial interfaceWorkerNavigator {  [SameObject] readonly attributePermissionspermissions;};[Exposed=(Window,Worker)]interfacePermissions {Promise<PermissionStatus>query(objectpermissionDesc);};dictionaryPermissionDescriptor {  requiredDOMStringname;};[Exposed=(Window,Worker)]interfacePermissionStatus :EventTarget {  readonly attributePermissionStatestate;  readonly attributeDOMStringname;  attributeEventHandleronchange;};enumPermissionState {"granted","denied","prompt",};dictionaryPermissionSetParameters {  requiredobjectdescriptor;  requiredPermissionStatestate;};

This section is non-normative.

The editors would like to thank Adrienne Porter Felt, Anne van Kesteren, Domenic Denicola, Jake Archibald and Wendy Seltzer for their help with the API design and editorial work.