Add optional_host_permissions docs

files/en-us/mozilla/add-ons/webextensions/api/permissions/contains/index.md

@@ -9,7 +9,7 @@ browser-compat: webextensions.api.permissions.contains
 
 Check whether the extension has the permissions listed in the given {{WebExtAPIRef("permissions.Permissions")}} object.
 
-The `Permissions` argument may contain either an origins property, which is an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), or a `permissions` property, which is an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both.
+The `Permissions` argument may contain either an origins property, which is an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), [optional_host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#optional_host_permissions), or a `permissions` property, which is an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both.
 
 This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). The promise is fulfilled with true only if all the extension currently has all the given permissions. For host permissions, if the extension's permissions [pattern-match](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) the permissions listed in `origins`, then they are considered to match.
 

files/en-us/mozilla/add-ons/webextensions/api/permissions/index.md

@@ -20,7 +20,7 @@ With the permissions API, an extension can ask for additional permissions at run
 
 - The extension can run with a smaller set of permissions, except when it actually needs them.
 - The extension can handle permission denial in a graceful manner, instead of presenting the user with a global "all or nothing" choice at install time. You can still get a lot out of that map extension, without giving it access to your location, for example.
-- The extension may need [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), but not know at install time which host permissions it needs. For example, the list of hosts may be a user setting. In this scenario, asking for a more specific range of hosts at runtime, can be an alternative to asking for "\<all_urls>" at install time.
+- The extension may need [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) or [optional_host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#optional_host_permissions), but not know at install time which host permissions it needs. For example, the list of hosts may be a user setting. In this scenario, asking for a more specific range of hosts at runtime, can be an alternative to asking for "\<all_urls>" at install time.
 
 To use the permissions API, decide which permissions your extension can request at runtime, and list them in [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions). After this, you can request any permissions that were included in `optional_permissions`. Requests may only be made in the handler for a user action (for example, a click handler).
 

files/en-us/mozilla/add-ons/webextensions/api/permissions/permissions/index.md

@@ -14,7 +14,7 @@ A `Permissions` object represents a collection of permissions.
 An {{jsxref("object")}} with the following properties:
 
 - `origins` {{optional_inline}}
-  - : An array of [match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns), representing [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions).
+  - : An array of [match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns), representing [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) or [optional_host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#optional_host_permissions).
 - `permissions` {{optional_inline}}
   - : An array of named permissions, including [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions) and [clipboard permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#clipboard_access).
 

files/en-us/mozilla/add-ons/webextensions/api/permissions/remove/index.md

@@ -9,7 +9,7 @@ browser-compat: webextensions.api.permissions.remove
 
 Ask to give up the permissions listed in the given {{WebExtAPIRef("permissions.Permissions")}} object.
 
-The `Permissions` argument may contain either an `origins` property, which is an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), or a `permissions` property, which is an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both. Permissions must come from the set of permissions defined in the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) manifest.json key.
+The `Permissions` argument may contain either an `origins` property, which is an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), [optional_host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#optional_host_permissions),or a `permissions` property, which is an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both. Permissions must come from the set of permissions defined in the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) manifest.json key.
 
 This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 

files/en-us/mozilla/add-ons/webextensions/api/permissions/request/index.md

@@ -9,7 +9,7 @@ browser-compat: webextensions.api.permissions.request
 
 Ask for the set of permissions listed in the given {{WebExtAPIRef("permissions.Permissions")}} object.
 
-The `Permissions` argument may contain either an `origins` property, which is an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), or a `permissions` property, which is an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both. Permissions must come from the set of permissions defined in the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) manifest.json key. The `origins` property may include permissions that match a subset of the hosts matched by an optional permission: for example, if optional_permissions include "\*://mozilla.org/", then `permissions.origins` may include "https\://developer.mozilla.org/".
+The `Permissions` argument may contain either an `origins` property, which is an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), [optional_host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#optional_host_permissions), or a `permissions` property, which is an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both. Permissions must come from the set of permissions defined in the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) manifest.json key. The `origins` property may include permissions that match a subset of the hosts matched by an optional permission: for example, if optional_permissions include "\*://mozilla.org/", then `permissions.origins` may include "https\://developer.mozilla.org/".
 
 The request can only be made inside the handler for a [user action](/en-US/docs/Mozilla/Add-ons/WebExtensions/User_actions).
 

files/en-us/mozilla/add-ons/webextensions/manifest.json/index.md

@@ -44,6 +44,7 @@ These are the `manifest.json` keys; these keys are available in Manifest V2 and
 - [name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/name)
 - [offline_enabled](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/offline_enabled)
 - [omnibox](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/omnibox)
+- [optional_host_permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_host_permissions) (Manifest V3 and above)
 - [optional_permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions)
 - [options_page](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_page)
 - [options_ui](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui)

files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_host_permissions/index.md

@@ -0,0 +1,54 @@
+---
+title: optional_host_permissions
+slug: Mozilla/Add-ons/WebExtensions/manifest.json/optional_host_permissions
+page-type: webextension-manifest-key
+browser-compat: webextensions.manifest.optional_host_permissions
+---
+
+{{AddonSidebar}}
+
+<table class="fullwidth-table standard-table">
+  <tbody>
+    <tr>
+      <th scope="row">Type</th>
+      <td><code>Array</code></td>
+    </tr>
+    <tr>
+      <th scope="row">Mandatory</th>
+      <td>No</td>
+    </tr>
+    <tr>
+      <th scope="row">Manifest version</th>
+      <td>3 or higher</td>
+    </tr>
+    <tr>
+      <th scope="row">Example</th>
+      <td>
+        <pre class="brush: json;">
+"optional_host_permissions": [
+  "*://developer.mozilla.org/*",
+  "*://*.example.org/*"
+]</pre
+        >
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+Use the `optional_host_permissions` key to enable runtime requests for access (access granted by the user after your extension has been installed) for the APIs in your extension that read or modify host data, such as {{WebExtAPIRef("cookies")}}, {{WebExtAPIRef("webRequest")}}, and {{WebExtAPIRef("tabs")}}. This key is an array of strings.
+
+See [`host_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/host_permissions) for more information on defining hosts.
+
+Use the {{webextapiref("permissions")}} API to ask for a permission. Asking for a permission may present the user with a dialog requesting they grant the host permission to your extension.
+
+## Example
+
+```json
+ "optional_host_permissions": ["*://developer.mozilla.org/*"]
+```
+
+Enables your extension to make a runtime request for privileged access to pages under `developer.mozilla.org`.
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_permissions/index.md

@@ -39,18 +39,15 @@ The [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/perm
 
 For advice on designing your request for runtime permissions, to maximize the likelihood that users grant them, see [Request permissions at runtime](https://extensionworkshop.com/documentation/develop/request-the-right-permissions/#request_permissions_at_runtime).
 
-Starting with Firefox 84, users will be able to manage optional permissions from the Firefox Add-ons Manager. Extensions that use optional permissions should listen for [browser.permissions.onAdded](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onAdded) and [browser.permissions.onRemoved](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onRemoved) API events to know when a user grants or revokes these permissions.
+Starting with Firefox 84, users can to manage optional permissions from the Firefox Add-ons Manager. Extensions that use optional permissions can listen for [browser.permissions.onAdded](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onAdded) and [browser.permissions.onRemoved](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onRemoved) API events to know when a user grants or revokes these permissions.
 
 The key can contain two kinds of permissions: host permissions and API permissions.
 
 ## Host permissions
 
-These are the same as the host permissions you can specify in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) key.
+These are the same as the host permissions you can specify in the [`host_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) key.
 
-> **Note:** When using Manifest V3 or higher:
->
-> - in Chrome, host permissions must be specified in the [`host_permission`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/host_permissions) manifest key.
-> - in Firefox, during the Manifest V3 developer preview, hosts can be in either `host_permissions` or `optional_permissions`. Subject to completion of [bug 1766026](https://bugzil.la/1766026), hosts will be specified in either `host_permissions` or `optional_host_permissions`.
+> **Note:** When using Manifest V3 or higher optional host permissions should be specified using the [`optional_host_permission`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_host_permissions) manifest key. Firefox introduced `optional_host_permission`in release 128, see [bug 1766026](https://bugzil.la/1766026), and allows for the continued use of `optional_permissions` to specify optional hosts. Use of `optional_host_permission` however is recommended.
 
 ## API permissions
 

files/en-us/mozilla/firefox/releases/128/index.md

@@ -58,6 +58,8 @@ This article provides information about the changes in Firefox 128 that affect d
 
 ## Changes for add-on developers
 
+- The [optional_host_permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_host_permissions) manifest key has been added. This key enables runtime requests for access (access granted by the user after an extension has been installed) for the APIs in the extension that read or modify host data ([Firefox bug 1766026](https://bugzil.la/1766026)).
+
 ### Removals
 
 ### Other