Permissions API
Note: This feature is available in Web Workers.
The Permissions API provides a consistent programmatic way to query the status of API permissions attributed to the current context, such as a web page or worker. For example, it can be used to determine if permission to access a particular feature or API has been granted, denied, or requires specific user permission.
Concepts and usage
Historically different APIs handle their own permissions inconsistently — for example the Geolocation API did not. The Permissions API provides the tools to allow developers to implement a consistent user experience for working with permissions.
The permissions from this API effectively aggregate all security restrictions for the context, including any requirement for an API to be used in a secure context, Permissions-Policy restrictions applied to the document, requirements for user interaction, and user prompts.
So, for example, if an API is restricted by permissions policy, the returned permission would be denied and the user would not be prompted for access.
The permissions property has been made available on the Permissions object that provides access to the Permissions API functionality.
Once you have this object you can then use the PermissionStatus for a specific API.
Requesting permission
If the permission status is prompt, the user must acknowledge a prompt to grant access to the feature.
The mechanism that triggers this prompt will depend on the specific API — it is not defined as part of the Permissions API. Generally the trigger is code calling a method to access or open the feature, or that registers for notifications from the feature that will subsequently access it.
Note that not all features require a prompt.
Permission might be granted by a Permission Policy, implicitly by transient activation, or via some other mechanism.
Revoking permission
Permission revocation is not managed by the API.
More specifically, a Permissions.revoke() method was proposed, but has since been removed from those browsers where it was implemented.
Users can manually remove permission for particular sites using browser settings:
- Firefox: Hamburger Menu > Settings > Privacy & Security > Permissions (then select the Settings button for the permission of interest).
- Chrome: Hamburger Menu > Settings > Show advanced settings. In the Privacy section, click Content Settings. In the resulting dialog, find the Location section and select Ask when a site tries to…. Finally, click Manage Exceptions and remove the permissions you granted to the sites you are interested in.
Permission-aware APIs
Not all APIs' permission statuses can be queried using the Permissions API. A non-exhaustive list of permission-aware APIs includes:
- Background Synchronization API:
background-sync(should always be granted) - Clipboard API:
clipboard-read,clipboard-write - Compute Pressure API:
compute-pressure - Geolocation API:
geolocation - Local Font Access API:
local-fonts - Media Capture and Streams API:
microphone,camera - Notifications API:
notifications - Payment Handler API:
payment-handler - Push API:
push - Screen Capture API:
captured-surface-control,display-capture - Screen Wake Lock API:
screen-wake-lock - Sensor APIs:
accelerometer,gyroscope,magnetometer,ambient-light-sensor - Storage Access API:
storage-access,top-level-storage-access - Storage API:
persistent-storage - Web Bluetooth API:
bluetooth - Web MIDI API:
midi - Window Management API:
window-management
Interfaces
Permissions-
Provides the core Permission API functionality, such as methods for querying and revoking permissions.
PermissionStatus-
Provides access to the current status of a permission, and an event handler to respond to changes in permission status.
Extensions to other interfaces
-
Provides access to the
Permissionsobject from the main context and worker context respectively.
Examples
We have created an example called Location Finder. You can view the source code on GitHub, or read more about how it works in our article Using the Permissions API.
The Permissions.query() example also so shows code that tests most permissions on the current browser and logs the result.
Specifications
| Specification |
|---|
| Permissions |