MDN’s new design is in Beta! A sneak peek:


Enables add-ons to request extra permissions at runtime, after they have been installed.

Add-ons need permissions to access many of the 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 add-on can rely on the access to the APIs it needs, because if it's running at all, the permissions have been granted.

With the permissions API, an add-on 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 add-on can run with a smaller set of permissions except when it actually needs them
  • the add-on 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 add-on without giving it access to your location, for example.
  • the add-on may need host permissions, but not know at install time exactly 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 add-on 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).


Represents a set of permissions.


Find out whether the add-on has the given set of permissions.
Get all the permissions this add-on currently has.
Give up a set of permissions.
Ask for a set of permissions.

Event handlers

Fired when a new permission is granted.
Fired when a permission is removed.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
requestYesNo55 *55 *Yes

Edge incompatibilities

Promises are not supported in Edge. Use callbacks instead.

Example Add-ons


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.

Document Tags and Contributors

 Contributors to this page: wbamberg
 Last updated by: wbamberg,