optional_permissions

Type Array
Mandatory No
Manifest version 2 or higher
Example 
"optional_permissions": [
  "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.

Note: When using Manifest V3 or higher:

  • in Chrome, host permissions must be specified in the host_permission manifest key.
  • in Firefox, during the Manifest V3 developer preview, hosts can be in either host_permissions or optional_permissions. Subject to completion of bug 1766026, hosts will be specified in either host_permissions or optional_host_permissions.

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
  • scripting (Manifest V3 or higher)
  • tabHide
  • tabs
  • topSites
  • webNavigation
  • webRequest
  • webRequestBlocking
  • webRequestFilterResponse
  • webRequestFilterResponse.serviceWorkerScript

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
  • webRequestFilterResponse
  • webRequestFilterResponse.serviceWorkerScript

Example

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

In Manifest V2 only, 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"]

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

© 2005–2023 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