optional_permissions
| Type | Array |
|---|---|
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
json |
Use the optional_permissions key to list permissions 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 can ask for after installation. To ask for a permission, use the permissions.request() API. Asking for a permission presents the user with a dialog requesting them to grant the permission to your extension, unless all the permissions requested are granted silently.
For advice on designing your request for runtime permissions, to maximize the likelihood that users grant them, see Request permissions at runtime.
Note:
Users can manage optional permissions from the Firefox Add-ons Manager. Extensions that use optional permissions can check for the permissions granted by the user with permissions.getAll() and listen for permissions.onAdded and permissions.onRemoved to know when a user grants or revokes permissions.
The key can contain 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, optional host permissions should be specified using the optional_host_permissions manifest key. Firefox introduced optional_host_permissions in release 128, see bug 1766026, and allows the continued use of optional_permissions to specify optional hosts. Use of optional_host_permissions, however, is recommended.
API permissions
The optional API permissions are:
activeTabbackgroundbookmarksbrowserSettingsbrowsingDataclipboardReadclipboardWritecontentSettingscontextMenuscookiesdebuggerdeclarativeNetRequestdeclarativeNetRequestFeedbackdeclarativeNetRequestWithHostAccessdevtoolsdownloadsdownloads.openfindgeolocationhistoryidlemanagementnativeMessagingnotificationspageCapturepkcs11privacyproxyscriptingsearchsessionstabHidetabGroupstabstopSitesuserScripts(optional-only)webNavigationwebRequestwebRequestBlockingwebRequestFilterResponsewebRequestFilterResponse.serviceWorkerScript
Check the compatibility table for browser-specific support details.
These optional permissions are granted silently, without a user prompt:
activeTabcookiesidletabGroupswebRequestwebRequestBlockingwebRequestFilterResponsewebRequestFilterResponse.serviceWorkerScript
Optional-only permissions
Optional permissions are generally available for use in the permissions key, so they can be requested at install time. However, some browsers support the concept of optional-only permissions, permissions that can only be requested at runtime. For example, in Firefox, optional-only permissions can be granted by the user from the extension's options page or using permissions.request(). Optional-only permissions must be requested individually and alone through the permissions.request() API.
The optional-only API permissions are:
userScripts(see userScripts permission)
Examples
json
"optional_permissions": ["*://developer.mozilla.org/*"]
In Manifest V2 only, enable the extension to ask for privileged access to pages under developer.mozilla.org.
json
"optional_permissions": ["tabs"]
Enable the extension to ask for access to the privileged pieces of the tabs API.
json
"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 | ||||||
|---|---|---|---|---|---|---|---|
optional_permissions
|
|
|
|
|
|
|
|
activeTab
|
|
|
|
|
|
|
|
alarms
|
|
|
|
|
|
|
|
background
|
|
|
|
|
|
|
|
bookmarks
|
|
|
|
|
|
|
|
browserSettings
|
|
|
|
|
|
|
|
browsingData
|
|
|
|
|
|
|
|
clipboardRead
|
|
|
|
|
|
|
|
clipboardWrite
|
|
|
|
|
|
|
|
contentSettings
|
|
|
|
|
|
|
|
contextMenus
|
|
|
|
|
|
|
|
cookies
|
|
|
|
|
|
|
|
declarativeNetRequest
|
|
|
|
|
|
|
|
declarativeNetRequestFeedback
|
|
|
|
|
|
|
|
declarativeNetRequestWithHostAccess
|
|
|
|
|
|
|
|
devtools
|
|
|
|
|
|
|
|
dns
|
|
|
|
|
|
|
|
downloads
|
|
|
|
|
|
|
|
downloads.open
|
|
|
|
|
|
|
|
find
|
|
|
|
|
|
|
|
geolocation
|
|
|
|
|
|
|
|
history
|
|
|
|
|
|
|
|
identity
|
|
|
|
|
|
|
|
idle
|
|
|
|
|
|
|
|
management
|
|
|
|
|
|
|
|
menus
|
|
|
|
|
|
|
|
nativeMessaging
|
|
|
|
|
|
|
|
notifications
|
|
|
|
|
|
|
|
pageCapture
|
|
|
|
|
|
|
|
pkcs11
|
|
|
|
|
|
|
|
privacy
|
|
|
|
|
|
|
|
proxy
|
|
|
|
|
|
|
|
scripting
|
|
|
|
|
|
|
|
search
|
|
|
|
|
|
|
|
sessions
|
|
|
|
|
|
|
|
storage
|
|
|
|
|
|
|
|
tabGroups
|
|
|
|
|
|
|
|
tabHide
|
|
|
|
|
|
|
|
tabs
|
|
|
|
|
|
|
|
topSites
|
|
|
|
|
|
|
|
unlimitedStorage
|
|
|
|
|
|
|
|
userScripts
|
|
|
|
|
|
|
|
webNavigation
|
|
|
|
|
|
|
|
webRequest
|
|
|
|
|
|
|
|
webRequestBlocking
|
|
|
|
|
|
|
|
webRequestFilterResponse
|
|
|
|
|
|
|
|
webRequestFilterResponse.serviceWorkerScript
|
|
|
|
|
|
|
|
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- In development. Supported in a pre-release version.
- In development. Supported in a pre-release version.
- No support
- No support
- See implementation notes.
- Uses a non-standard name
- Has more compatibility info.