Extensions need permissions to access more powerful WebExtension APIs. They can ask for permissions at install time, by including the permissions they need in thepermissions 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 theoptional_permissions manifest.json key. Note that some permissions are not allowed inoptional_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 needhost 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 inoptional_permissions. After this, you can request any permissions that were included inoptional_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 forbrowser.permissions.onAdded andbrowser.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, seeRequest permissions at runtime.

This page was last modified onJul 17, 2025 byMDN contributors.