W3cubDocs

/Web Extensions

optional_permissions

Type Array
Mandatory No
Example 
"optional_permissions": [
  "*://developer.mozilla.org/*",
  "webRequest"
]

Use the optional_permissions key to list permissions that you want to ask for at runtime, after your extension has been installed.

The permissions key lists permissions that your extension needs before it can be installed. In contrast, optional_permissions lists permissions that your extension doesn't need at install time but it may ask for after it has been installed. To ask for a permission, use the permissions API. Asking for a permission may present the user with a dialog requesting them to grant the permission to your extension.

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

Starting with Firefox 84, users will be able to manage optional permissions from the Firefox 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.

The key can contain two kinds of permissions: host permissions and API permissions.

Host permissions

These are the same as the host permissions you can specify in the permissions key.

API permissions

You can include any of the following here, but not in all browsers: check the compatibility table for browser-specific details.

  • activeTab
  • background
  • bookmarks
  • browserSettings
  • clipboardRead
  • clipboardWrite
  • contentSettings
  • contextMenus
  • cookies
  • debugger
  • downloads
  • downloads.open
  • find
  • geolocation
  • history
  • idle
  • management
  • nativeMessaging
  • notifications
  • pageCapture
  • privacy
  • tabHide
  • tabs
  • topSites
  • webNavigation
  • webRequest
  • webRequestBlocking

Note that this is a subset of the API permissions allowed in permissions.

Of this set, the following permissions are granted silently, without a user prompt:

  • activeTab
  • cookies
  • idle
  • webRequest
  • webRequestBlocking

Example

 "optional_permissions": ["*://developer.mozilla.org/*"]

Enable the extension to ask for privileged access to pages under developer.mozilla.org.

  "optional_permissions": ["tabs"]

Enable the extension to ask for access to the privileged pieces of the tabs API.

  "optional_permissions": ["*://developer.mozilla.org/*", "tabs"]

Enable the extension to ask for both of the above permissions.

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
optional_permissions
Yes
79
55
?
Yes
14
?
?
55
?
?
?
activeTab
No
No
55
?
No
14
?
?
55
?
?
?
background
Yes
79
No
?
Yes
No
?
?
No
?
?
?
bookmarks
Yes
79
55
?
Yes
No
?
?
No
?
?
?
browserSettings
No
No
57
?
No
No
?
?
57
?
?
?
browsingData
No
No
77
?
No
No
?
?
No
?
?
?
clipboardRead
Yes
79
55
?
Yes
No
?
?
55
?
?
?
clipboardWrite
Yes
79
55
?
Yes
14
?
?
55
?
?
?
contentSettings
Yes
79
No
?
Yes
No
?
?
No
?
?
?
contextMenus
Yes
79
No
?
Yes
14
?
?
No
?
?
?
cookies
Yes
79
55
?
Yes
14
?
?
55
?
?
?
debugger
Yes
79
No
?
Yes
No
?
?
No
?
?
?
downloads
No
No
60
?
No
No
?
?
60
?
?
?
downloads_open
No
No
60
?
No
No
?
?
60
?
?
?
find
No
No
57
?
No
No
?
?
No
?
?
?
geolocation
No
No
55
?
No
No
?
?
55
?
?
?
history
Yes
79
55
?
Yes
No
?
?
No
?
?
?
idle
Yes
79
55
?
Yes
No
?
?
55
?
?
?
management
Yes
79
77
?
Yes
No
?
?
No
?
?
?
nativeMessaging
No
No
87
?
No
No
?
?
No
?
?
?
notifications
Yes
79
55
?
Yes
No
?
?
55
?
?
?
pageCapture
Yes
79
No
?
Yes
No
?
?
No
?
?
?
pkcs11
No
No
77
?
No
No
?
?
No
?
?
?
privacy
Yes
79
75
?
Yes
No
?
?
No
?
?
?
proxy
No
No
77
?
No
No
?
?
No
?
?
?
sessions
No
No
77
?
No
No
?
?
No
?
?
?
tabHide
No
No
61
?
No
No
?
?
No
?
?
?
tabs
Yes
79
55
?
Yes
14
?
?
55
?
?
?
topSites
Yes
79
55
?
Yes
No
?
?
55
?
?
?
webNavigation
Yes
79
55
?
Yes
14
?
?
55
?
?
?
webRequest
Yes
79
55
?
Yes
14
?
?
55
?
?
?
webRequestBlocking
Yes
79
55
?
Yes
No
?
?
55
?
?
?

© 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/manifest.json/optional_permissions