host\_permissions
=================

|  |  |
| --- | --- |
| Type | `Array` |
| Mandatory | No |
| Manifest version | 3 or higher |
| Example | 
```json
"host\_permissions": [
  "\*://developer.mozilla.org/\*",
  "\*://\*.example.org/\*"
]
```
 |

Use the `host_permissions` key to request access for the APIs in your extension that read or modify host data, such as `cookies`, `webRequest`, and `tabs`. This key is an array of strings, and each string is a request for a permission.

### Requested permissions and user prompts

Most browsers treat `host_permission` as optional. If you request permissions using this key, users *may* get prompted to grant those permissions during installation. As of June 2023, Safari, Firefox, and some Chromium-based browsers don't prompt the user during installation.

Users can also grant or revoke host permissions on an ad hoc basis. For example, in Firefox, users can do this using the extensions panel.

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 (though not for requests from content scripts, as was the case in Manifest V2).
* 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.

In Firefox extensions get host permissions for their origin, which is of the form:


```url
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()`:


```js
browser.extension.getURL("");
// moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/
```

Example
-------


```json
 "host\_permissions": ["\*://developer.mozilla.org/\*"]
```


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

Example extensions
------------------

* dnr-redirect-url
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.