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 request permissions at install time by including them in thepermissions manifest.json key. The main advantages of asking for permissions at install time are:

The extension asks the user only once, so it's less disruptive for them, and a simpler decision.
The extension can rely on the access to the APIs it needs, as it knows the permissions are granted.

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

Using the permissions API, an extension can request additional permissions at runtime. The extension must list these permissions in

optional_permissions key of its manifest.json file for origins and API permissions.
gecko.data_collection_permissions.optional property of thebrowser_specific_settings key of its manifest.json file for data collection permissions.

The main advantages of requesting permissions at runtime are:

The extension can run with a smaller set of permissions, except when it needs them.
The extension can gracefully handle permission denial, instead of presenting the user with a global "all or nothing" choice at install time. For example, a user can get a lot out of that map extension without giving it access to their location.
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, requesting a more specific range of hosts at runtime can be an alternative to asking for "<all_urls>" at install time.

Note that some permissions are not allowed inoptional_permissions.

To use the permissions API, decide which permissions your extension can request at runtime, and list them inoptional_permissions andbrowser_specific_settings.gecko.data_collection_permissions.optional. After this, you can request any permissions included inoptional_permissions orbrowser_specific_settings.gecko.data_collection_permissions.optional. The extension can only make these requests in the handler for a user action (for example, a click handler).

Starting with Firefox 84, users can 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.

Types

permissions.Permissions: Represents a set of permissions.

Methods

permissions.contains(): Checks whether the extension has specific permissions.
permissions.getAll(): Retrieves all the permissions currently granted to the extension.
permissions.remove(): Gives up a set of permissions.
permissions.request(): Asks for a set of permissions.