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.

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 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.
  • bypass tracking protection if the host is a full domain without wildcards. Doesn't work with <all_urls>.

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
  • contentSettings
  • contextMenus
  • contextualIdentities
  • cookies
  • debugger
  • dns
  • downloads
  • downloads.open
  • find
  • geolocation
  • history
  • identity
  • idle
  • management
  • menus
  • nativeMessaging
  • notifications
  • pageCapture
  • pkcs11
  • privacy
  • proxy
  • search
  • sessions
  • storage
  • tabHide
  • tabs
  • theme
  • topSites
  • 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 ability to inject JavaScript or CSS into the tab programmatically, using browser.tabs.executeScript and browser.tabs.insertCSS
  • access to the privileged parts of the tabs API for the current tab: Tab.url, Tab.title, and Tab.faviconUrl.

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 just in response to a user action.

Note that 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 that's not the currently active tab.

Clipboard access

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

  • clipboardWrite: write to the clipboard using document.execCommand("copy") or document.execCommand("cut")
  • clipboardRead: read from the clipboard using document.execCommand("paste")

See Interact with the clipboard for all the details on this.

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

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic support Yes144848 Yes
activeTab Yes No4848 Yes
alarms Yes No4548 Yes
background10 No No No No
bookmarks Yes1545 No Yes
browserSettings No No5656 No
browsingData Yes No5356 Yes
clipboardRead Yes No5454 Yes
clipboardWrite Yes No5151 Yes
contentSettings Yes No No No Yes
contextMenus Yes14551 No Yes
contextualIdentities No No5353 No
cookies Yes144548 Yes
debugger Yes No No No Yes
dns No No6060 No
downloads Yes No4748 Yes
downloads.open Yes No4848 Yes
find No No57 No No
geolocation Yes145454 Yes
history Yes No49 No Yes
identity Yes No53 No Yes
idle Yes154548 Yes
management Yes No5151 Yes
menus No No53 No No
nativeMessaging291550 No16
notifications5 No454825
pageCapture Yes No No No Yes
pkcs11 No No58 No No
privacy Yes No5454 Yes
proxy No No5555 No
sessions Yes No52 No Yes
storage Yes144548 Yes
tabs Yes144554 Yes
theme No No55 No No
topSites Yes No5252 Yes
unlimitedStorage Yes145656 No
webNavigation Yes14454817
webRequest Yes144548 Yes
webRequestBlocking Yes144548 Yes

1. Available as an alias to the menus permission.

Document Tags and Contributors

Last updated by: wbamberg,