W3cubDocs

/Web Extensions

permissions

Enables extensions to request extra permissions at runtime, after they have been installed.

Extensions need permissions to access more powerful WebExtension APIs. They can ask for permissions at install time, by including the permissions they need in the permissions manifest.json key. The main advantages of asking for permissions at install time are:

  • The user is only asked once, so it's less disruptive for them, and a simpler decision.
  • The extension can rely on the access to the APIs it needs, because if already running, the permissions have been granted.

In most major browsers, users can see if their installed extensions request advanced permissions through the browser's extensions manager.

With the permissions API, an extension can ask for additional permissions at runtime. These permissions need to be listed in the optional_permissions manifest.json key. Note that some permissions are not allowed in optional_permissions. The main advantages of this are:

  • The extension can run with a smaller set of permissions, except when it actually needs them.
  • The extension can handle permission denial in a graceful manner, instead of presenting the user with a global "all or nothing" choice at install time. You can still get a lot out of that map extension, without giving it access to your location, for example.
  • The extension may need host permissions, but not know at install time which host permissions it needs. For example, the list of hosts may be a user setting. In this scenario, asking for a more specific range of hosts at runtime, can be an alternative to asking for "<all_urls>" at install time.

To use the permissions API, decide which permissions your extension can request at runtime, and list them in optional_permissions. After this, you can request any permissions that were included in optional_permissions. Requests may only be made in the handler for a user action (for example, a click handler).

Starting with Firefox 84, users will be able to manage optional permissions of installed extensions from the Add-ons Manager. Extensions that use optional permissions should listen for browser.permissions.onAdded and browser.permissions.onRemoved API events to know when a user grants or revokes these permissions.

For advice on designing your request for runtime permissions, to maximize the likelihood that users grant them, see Request permissions at runtime.

Types

permissions.Permissions
Represents a set of permissions.

Methods

permissions.contains()
Discover an extension's given set of permissions.
permissions.getAll()
Get all the permissions this extension currently has.
permissions.remove()
Give up a set of permissions.
permissions.request()
Ask for a set of permissions.

Event handlers

permissions.onAdded
Fired when a new permission is granted.
permissions.onRemoved
Fired when a permission is removed.

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
contains
Yes
79
55
?
Yes
14
?
?
55
?
?
?
getAll
Yes
79
55
?
Yes
14
?
?
55
?
?
?
onAdded
Yes
79
77
There is a polyfill available for earlier versions.
?
Yes
14
?
?
No
?
?
?
onRemoved
Yes
79
77
There is a polyfill available for earlier versions.
?
Yes
14
?
?
No
?
?
?
Permissions
Yes
79
55
?
Yes
14
?
?
55
?
?
?
remove
Yes
79
55
?
Yes
14
Removing <all_urls> or *://*/* origins will remove previously granted permission to request specific origin patterns and will stop automatically prompting the user for access to any visited website via the extension's access popover in the toolbar.
?
?
55
?
?
?
request
Yes
79
55
["It's not possible to request permissions from a sidebar document (bug 1493396).", "Before version 75, permissions cannot be requested from popup panels (see bug 1432083).", "Before version 61, permissions cannot be requested from options pages embedded in about:addons (see bug 1382953)."]
?
Yes
14
["Requesting <all_urls> or *://*/* origins will grant permission to request specific origin patterns and automatically prompt the user for access to any visited website via the extension's access popover in the toolbar.", "The user will be prompted again for permissions that have been previously granted and then removed.", "Supported permissions will be granted without prompting the user. Only specific origin patterns will prompt the user."]
?
?
Yes
?
?
?

See also

Example extensions

Note: This API is based on Chromium's chrome.permissions API.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions