W3cubDocs

/Web Extensions

permissions

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

Use the permissions key to request special powers for your extension. This key is an array of strings, and each string is a request for a permission.

If you request permissions using this key, then the browser may inform the user at install time that the extension is requesting certain privileges, and ask them to confirm that they are happy to grant these privileges. The browser may also allow the user to inspect an extension's privileges after installation. As the request to grant privileges may impact on users' willingness to install your extension, requesting privileges is worth careful consideration. For example, you want to avoid requesting unnecessary permissions and may want to provide information about why you are requesting permissions in your extension's store description. More information on the issues you should consider is provided in the article Request the right permissions.

For information on how to test and preview permission requests, see Test permission requests on the Extension Workshop site.

The key can contain three kinds of permissions:

  • host permissions
  • API permissions
  • the activeTab permission

Host permissions

Host permissions are specified as match patterns, and each pattern identifies a group of URLs for which the extension is requesting extra privileges. For example, a host permission could be "*://developer.mozilla.org/*".

The extra privileges include:

  • XMLHttpRequest and fetch access to those origins without cross-origin restrictions (even for requests made from content scripts)
  • the ability to read tab-specific metadata without the "tabs" permission, such as the url, title, and favIconUrl properties of tabs.Tab objects
  • the ability to inject scripts programmatically (using tabs.executeScript()) into pages served from those origins
  • the ability to receive events from the webrequest API for these hosts
  • the ability to access cookies for that host using the cookies API, as long as the "cookies" API permission is also included.
  • bypassing tracking protection for extension pages where a host is specified as a full domain or with wildcards. Content scripts, however, can only bypass tracking protection for hosts specified with a full domain.

In Firefox, from version 56 onwards, extensions automatically get host permissions for their own origin, which is of the form:

moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/

where 60a20a9b-1ad4-af49-9b6c-c64c98c37920 is the extension's internal ID. The extension can get this URL programmatically by calling extension.getURL():

browser.extension.getURL("");
// moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/

API permissions

API permissions are specified as keywords, and each keyword names a WebExtension API that the extension would like to use.

The following keywords are currently available:

  • activeTab
  • alarms
  • background
  • bookmarks
  • browserSettings
  • browsingData
  • captivePortal
  • clipboardRead
  • clipboardWrite
  • contentSettings
  • contextMenus
  • contextualIdentities
  • cookies
  • debugger
  • dns
  • downloads
  • downloads.open
  • find
  • geolocation
  • history
  • identity
  • idle
  • management
  • menus
  • menus.overrideContext
  • nativeMessaging
  • notifications
  • pageCapture
  • pkcs11
  • privacy
  • proxy
  • search
  • sessions
  • storage
  • tabHide
  • tabs
  • theme
  • topSites
  • unlimitedStorage
  • webNavigation
  • webRequest
  • webRequestBlocking

In most cases the permission just grants access to the API, with the following exceptions:

activeTab permission

This permission is specified as "activeTab". If an extension has the activeTab permission, then when the user interacts with the extension, the extension is granted extra privileges for the active tab only.

"User interaction" includes:

  • the user clicks the extension's browser action or page action
  • the user selects its context menu item
  • the user activates a keyboard shortcut defined by the extension

The extra privileges are:

The intention of this permission is to enable extensions to fulfill a common use case, without having to give them very powerful permissions. Many extensions want to "do something to the current page when the user asks".

For example, consider an extension that wants to run a script in the current page when the user clicks a browser action. If the activeTab permission did not exist, the extension would need to ask for the host permission <all_urls>. But this gives the extension more power than it needs: it could now execute scripts in any tab, any time it likes, instead of just the active tab and only in response to a user action.

Note: You can only get access to the tab/data that was there, when the user interaction occurred (e.g. the click). When the active tab navigates away (e.g., due to finishing loading or some other event), the permission does not grant you access to the tab anymore.

Usually the tab that's granted activeTab is just the currently active tab, except in one case. The menus API enables an extension to create a menu item which is shown if the user context-clicks on a tab (that is, on the element in the tabstrip that enables the user to switch from one tab to another).

If the user clicks such an item, then the activeTab permission is granted for the tab the user clicked, even if it's not the currently active tab (as of Firefox 63, bug 1446956).

Clipboard access

There are two permissions which enables the extension to interact with the clipboard:

clipboardWrite
Write to the clipboard using Clipboard.write(), Clipboard.writeText(), document.execCommand("copy") or document.execCommand("cut")
clipboardRead
Read from the clipboard using Clipboard.read(), Clipboard.readText() or document.execCommand("paste")

See Interact with the clipboard for more details.

Unlimited storage

The unlimitedStorage permission:

  • Enables extensions to exceed any quota imposed by the storage.local API
  • In Firefox, enables extensions to create a "persistent" IndexedDB database without the browser prompting the user for permission at the time the database is created.

Example

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

Request privileged access to pages under developer.mozilla.org.

  "permissions": ["tabs"]

Request access to the privileged pieces of the tabs API.

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

Request 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
permissions
Yes
14
48
?
Yes
14
?
?
48
?
?
?
activeTab
Yes
79
48
?
Yes
14
?
?
48
?
?
?
alarms
Yes
79
48
?
Yes
14
?
?
48
?
?
?
background
10
79
No
?
No
No
?
?
No
?
?
?
bookmarks
Yes
15
48
?
Yes
No
?
?
No
?
?
?
browserSettings
No
No
56
?
No
No
?
?
56
?
?
?
browsingData
Yes
79
53
?
Yes
No
?
?
56-79
85
?
?
?
captivePortal
No
No
68
?
No
No
?
?
No
?
?
?
clipboardRead
Yes
79
54
?
Yes
No
?
?
54
?
?
?
clipboardWrite
Yes
79
51
?
Yes
14
?
?
51
?
?
?
contentSettings
Yes
79
No
?
Yes
No
?
?
No
?
?
?
contextMenus
Yes
14
55
Available as an alias to the menus permission.
?
Yes
14
Available as an alias to the menus permission.
?
?
No
?
?
?
contextualIdentities
No
No
53
?
No
No
?
?
53
?
?
?
cookies
Yes
14
48
?
Yes
14
?
?
48
?
?
?
debugger
Yes
79
No
?
Yes
No
?
?
No
?
?
?
dns
No
No
60
?
No
No
?
?
60
?
?
?
downloads
Yes
79
48
?
Yes
No
?
?
48
?
?
?
downloads_open
Yes
79
48
?
Yes
No
?
?
48
?
?
?
find
No
No
57
?
No
No
?
?
No
?
?
?
geolocation
Yes
14
54
?
Yes
No
?
?
54
?
?
?
history
Yes
79
49
?
Yes
No
?
?
No
?
?
?
identity
Yes
79
53
?
Yes
No
?
?
No
?
?
?
idle
Yes
15
48
?
Yes
No
?
?
48
?
?
?
management
Yes
79
51
?
Yes
No
?
?
51
?
?
?
menus
No
No
53
?
No
14
?
?
No
?
?
?
nativeMessaging
29
15
50
?
16
14
?
?
No
?
?
?
notifications
5
79
48
?
25
No
?
?
48
?
?
?
pageCapture
Yes
79
No
?
Yes
No
?
?
No
?
?
?
pkcs11
No
No
58
?
No
No
?
?
No
?
?
?
privacy
Yes
79
54
?
Yes
No
?
?
54
?
?
?
proxy
33
79
55
?
No
No
?
?
55
?
?
?
search
No
No
63
?
No
No
?
?
No
?
?
?
sessions
Yes
79
52
?
Yes
No
?
?
No
?
?
?
storage
Yes
14
48
?
Yes
14
?
?
48
?
?
?
tabHide
No
No
61
?
No
No
?
?
No
?
?
?
tabs
Yes
14
48
?
Yes
14
?
?
54
?
?
?
theme
No
No
55
?
No
No
?
?
No
?
?
?
topSites
Yes
79
52
?
Yes
No
?
?
52
?
?
?
unlimitedStorage
Yes
14
56
?
No
14
Does not grant an unlimited storage quota. Grants a 10 MB storage quota, instead of the standard 5 MB.
?
?
56
?
?
?
webNavigation
Yes
14
48
?
17
14
?
?
48
?
?
?
webRequest
Yes
14
48
?
Yes
14
?
?
48
?
?
?
webRequestBlocking
Yes
14
48
?
Yes
No
?
?
48
?
?
?

© 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/permissions