Declare permissions

To use most extension APIs and features, you must declare your extension's intent in the manifest's permissions fields. Extensions can request the following categories of permissions, specified using the respective manifest keys:

"permissions"

Contains items from a list of known strings. Changes may trigger a warning.

"optional_permissions"

Granted by the user at runtime, instead of at install time.

"content_scripts.matches"

Contains one or more match patterns that allows content scripts to inject into one or more hosts. Changes may trigger a warning.

"host_permissions"

Contains one or more match patterns that give access to one or more hosts. Changes may trigger a warning.

"optional_host_permissions"

Granted by the user at runtime, instead of at install time.

Permissions help to limit damage if your extension is compromised by malware. Some permission warning are displayed to users for their consent before installation or at runtime, as detailed in Permission with warnings.

Consider using optional permissions wherever the functionality of your extension permits, to provide users with informed control over access to resources and data. For more information, see the platform vision statement.

If an API requires a permission, its documentation explains how to declare it. For an example, see Storage API.

# Manifest

The following is an example of the permissions section of a manifest file:

{
  "name": "Permissions Extension",
  ...
  "permissions": [
    "activeTab",
    "contextMenus",
    "storage"
  ],
  "optional_permissions": [
    "topSites",
  ],
  "host_permissions": [
    "https://www.developer.chrome.com/*"
  ],
  "optional_host_permissions":[
    "https://*/*",
    "http://*/*"
  ],
  ...
  "manifest_version": 3
}

# Host permissions

Host permissions allow extensions to interact with the URL's matching patterns. Some Chrome APIs require host permissions in addition to their own API permissions, which are documented on each reference page. Here are some examples:

• Make fetch() requests from the extension service worker and extension pages.
• Read and query the sensitive tab properties (url, title, and favIconUrl) using the chrome.tabs API.
• Inject a content script programmatically.
• Monitor and control the network requests with the chrome.webRequest API.
• Access cookies with the chrome.cookies API.
• Redirect and modify requests and response headers using chrome.declarativeNetRequest API.

# Permissions with warnings

When an extension requests multiple permissions, and many of them display warnings on installation, the user will see a list of warnings, like in the following example:

Users are more likely to trust an extension with limited warnings or when permissions are explained to them. Consider implementing optional permissions or a less powerful API to avoid alarming warnings. For a complete list of best practices, see Permission warnings guidelines.

Adding or changing match patterns in the "host_permissions" and "content_scripts.matches" fields will also trigger a warning. To learn more, see Updating permissions.

# Allow access

If your extension needs to run on file:// URLs or operate in incognito mode, users must give the extension access on its details page. You can find instructions for opening the details page under Manage your extensions.

To detect whether the user has allowed access, you can call extension.isAllowedIncognitoAccess() or extension.isAllowedFileSchemeAccess().

# Permissions list

Here's the list of permissions. See Permission warnings for a list of permission warnings.

"accessibilityFeatures.modify"

Lets extensions modify accessibility states when using the chrome.accessibilityFeatures API.

"accessibilityFeatures.read"

Lets extensions read accessibility states when using the chrome.accessibilityFeatures API.

"activeTab"

Gives temporary access to the active tab through a user gesture. See activeTab for details.

"alarms"

Gives access to the chrome.alarms API.

"audio"

Gives access to the chrome.audio API.

"background"

Makes Chrome start up early (as soon as the user logs into their computer, before they launch Chrome), and shut down late (even after its last window is closed, until the user explicitly quits Chrome).

"bookmarks"

Gives access to the chrome.bookmarks API.

"browsingData"

Gives access to the chrome.browsingData API.

"certificateProvider"

Gives access to the chrome.certificateProvider API.

"contentSettings"

Gives access to the chrome.contentSettings API.

"contextMenus"

Gives access to the chrome.contextMenus API.

"cookies"

Gives access to the chrome.cookies API.

"debugger"

Gives access to the chrome.debugger API.

"declarativeContent"

Gives access to the chrome.declarativeContent API.

"declarativeNetRequest"

Gives access to the chrome.declarativeNetRequest API.

"declarativeNetRequestWithHostAccess"

Gives access to the chrome.declarativeNetRequest API when host permissions are required.

"declarativeNetRequestFeedback"

Gives permission to write errors and warnings to the DevTools console when using the chrome.declarativeNetRequest API. This permission is for use with unpacked extensions and is ignored for extensions installed from the Chrome Web Store.

"dns"

Gives access to the chrome.dns API.

"desktopCapture"

Gives access to the chrome.desktopCapture API.

"documentScan"

Gives access to the chrome.documentScan API.

"downloads"

Gives access to the chrome.downloads API.

"downloads.open"

Allows the use of chrome.downloads.open().

"downloads.ui"

Allows the use of chrome.downloads.setUiOptions().

"enterprise.deviceAttributes"

Gives access to the chrome.enterprise.deviceAttributes API.

"enterprise.hardwarePlatform"

Gives access to the chrome.enterprise.hardwarePlatform API.

"enterprise.networkingAttributes"

Gives access to the chrome.enterprise.networkingAttributes API.

"enterprise.platformKeys"

Gives access to the chrome.enterprise.platformKeys API.

"favicon"

Grants access to the Favicon API.

"fileBrowserHandler"

Gives access to the chrome.fileBrowserHandler API.

"fileSystemProvider"

Gives access to the chrome.fileSystemProvider API.

"fontSettings"

Gives access to the chrome.fontSettings API.

"gcm"

Gives access to the chrome.gcm and chrome.instanceID APIs.

"geolocation"

Allows the extension to use the geolocation API without prompting the user for permission.

"history"

Gives access to the chrome.history API.

"identity"

Gives access to the chrome.identity API.

"idle"

Gives access to the chrome.idle API.

"loginState"

Gives access to the chrome.loginState API.

"management"

Gives access to the chrome.management API.

"nativeMessaging"

Gives access to the native messaging API.

"notifications"

Gives access to the chrome.notifications API.

"offscreen"

Gives access to the chrome.offscreen API.

"pageCapture"

Gives access to the chrome.pageCapture API.

"platformKeys"

Gives access to the chrome.platformKeys API.

"power"

Gives access to the chrome.power API.

"printerProvider"

Gives access to the chrome.printerProvider API.

"printing"

Gives access to the chrome.printing API.

"printingMetrics"

Gives access to the chrome.printingMetrics API.

"privacy"

Gives access to the chrome.privacy API.

"processes"

Gives access to the chrome.processes API.

"proxy"

Gives access to the chrome.proxy API.

"runtime"

Gives access to runtime.conntectNative() and runtime.sendNatriceMessage(). For all other features of the runtime namespace, no permission is required.

"scripting"

Gives access to the chrome.scripting API.

"search"

Gives access to the chrome.search API.

"sessions"

Gives access to the chrome.sessions API.

"sidePanel"

Gives access to the chrome.sidePanel API.

"storage"

Gives access to the chrome.storage API.

"system.cpu"

Gives access to the chrome.system.cpu API.

"system.display"

Gives access to the chrome.system.display API.

"system.memory"

Gives access to the chrome.system.memory API.

"system.storage"

Gives access to the chrome.system.storage API.

"tabCapture"

Gives access to the chrome.tabCapture API.

"tabGroups"

Gives access to the chrome.tabGroups API.

"tabs"

Gives access to privileged fields of the Tab objects used by several APIs, including chrome.tabs and chrome.windows. You usually won't need to declare this permission to use those APIs.

"topSites"

Gives access to the chrome.topSites API.

"tts"

Gives access to the chrome.tts API.

"ttsEngine"

Gives access to the chrome.ttsEngine API.

"unlimitedStorage"

Provides an unlimited quota for chrome.storage.local, IndexedDB, Cache Storage and Origin Private File System. For more information, see Storage and cookies.

"vpnProvider"

Gives access to the chrome.vpnProvider API.

"wallpaper"

Gives access to the chrome.wallpaper API.

"webAuthenticationProxy"

Gives access to the chrome.webAuthenticationProxy API.

"webNavigation"

Gives access to the chrome.webNavigation API.

"webRequest"

Gives access to the chrome.webRequest API.

"webRequestBlocking"

Allows the use of the chrome.webRequest API for blocking.