Declare permissions

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:

"permissions"

contains items from a list of known strings (such as "geolocation"). Changes may trigger a warning.

"optional_permissions"

are like regular permissions, but are granted by the user at runtime, rather than in advance.

"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"

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.

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.

# Manifest

The following is an example of the permissions part 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 permission, which are documented on each reference page. The following are a few examples of what host permissions allow extensions to do:

• 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.

# 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.

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.