host_permissions

Requested permissions and user prompts

Users can grant or revoke host permissions on an ad hoc basis. Therefore, most browsers treat host_permissions as optional.

On installation, when you request permissions using this key:

• Until Firefox 126, a Manifest V3 extension's requested host permissions weren't displayed in the install prompt. From Firefox 127, host permissions listed in host_permissions and content_scripts are displayed in the install prompt. However, if an extension update requests new host permissions, these are not shown to the user. See (Firefox bug 1893232).
• Chrome displays the permissions in the install prompt.
• Safari doesn't display requested host permissions in the install prompt.

Your extension can check whether it has all the required permissions immediately after installation using permissions.contains. If it doesn't have the necessary permissions, it can request them using permissions.request. Providing an onboarding step to explain why some permissions are necessary before requesting them might also be helpful.

As the request to grant host permissions may impact users' willingness to install your extension, requesting host permissions is worth careful consideration. For example, you want to avoid requesting unnecessary host permissions and may want to provide information about why you are requesting host permissions in your extension's store description. The article Request the right permissions provides more information on the issues you should consider.

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

Format

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, but not for requests 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.
• the ability to create and retrieve WebAuthn credentials. See Use Web Authn API in web extensions for details.

Example

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

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

Example extensions

• dnr-redirect-url

Browser compatibility