Welcome What's new in Chrome extensions Get help with Chrome extensions API reference Samples
Welcome What's new in Chrome extensions Get help with Chrome extensions API reference Samples

Declare permissions

Published on Updated on

To use most Chrome APIs, your extension must declare its intent in the permissions fields of the manifest. Extensions can request the following categories of permissions, specified using the respective manifest keys:

contains items from a list of known strings (such as "geolocation"). Changes may trigger a warning.
are like regular permissions, but are granted by the user at runtime, rather than in advance.
contains one or more match patterns that allows content scripts to inject into one or more hosts. Changes may trigger a warning.
contains one or more match patterns that give access to one or more hosts. Changes may trigger a warning.
are like regular host_permissions, but are granted by the user at runtime, rather than 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. See the platform vision to better understand this recommendation.

If an API requires a permission, then its documentation tells you how to do so. For example, the Storage API page shows how to declare the "storage" permission.


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


"name": "Permissions Extension",
"permissions": [
"optional_permissions": [
"host_permissions": [
"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 permission, which are documented on each reference page. The following are a few examples of what host permissions allow extensions to do:


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

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:

Extension permission warnings on installation

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.

Allow access

If your extension needs to run on file:// URLs or needs to operate in incognito mode, users will have to give the extension access on the extension's details page.

How to allow access to file URLs and incognito pages

  1. Right-click on the extension icon in Chrome.

  2. Choose Manage Extension.

    Extension context menu
    Extension menu
  1. Scroll down to enable access to file URLs or incognito mode.

    Allow file URLs and incognito mode on the extension detail page
    Access enabled to file URLs and incognito mode.

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

Permissions list

The following table lists the currently available permissions. See the Permission warnings table for a list of permission warnings.

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

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

Note: Disabled extensions are treated as if they aren't installed.
"bookmarks"Gives access to the chrome.bookmarks API.
"browsingData"Gives access to the chrome.browsingData API.
"certificateProvider"Gives access to the chrome.certificateProvider API.
"clipboardRead"Required if the extension uses document.execCommand('paste').
"clipboardWrite"Required if the extension uses document.execCommand('copy') or document.execCommand('cut').
"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 your extension access to the chrome.declarativeNetRequest API. Some operations may require host permissions to perform.
"declarativeNetRequestWithHostAccess"Gives your extension access to the chrome.declarativeNetRequest API, but requires host permissions to the request URL and initiator to act on a request.
"declarativeNetRequestFeedback"Gives access to events and methods within the chrome.declarativeNetRequest API which returns information on declarative rules matched.
"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"Permission required to use chrome.downloads.open()
"downloads.ui"Permission required to use 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.
"experimental"Required if the extension uses any chrome.experimental.* APIs.
"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 API.
"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.
"scripting"Gives access to the chrome.scripting 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. In many circumstances your extension will not need to declare the "tabs" permission to make use of these 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 storing client-side data, such as databases and local storage files. Without this permission, the extension is limited to 10 MB of local storage.
Note: This permission applies only to Web SQL Database and application cache (see issue 58985). Also, it doesn't currently work with wildcard subdomains such as http://*.example.com.
"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"Required if the extension uses the chrome.webRequest API in a blocking fashion.

Updated on Improve article

This site uses cookies to deliver and enhance the quality of its services and to analyze traffic. If you agree, cookies are also used to serve advertising and to personalize the content and advertisements that you see. Learn more about our use of cookies.