permissions.request()

Asks the user for the permissions listed in a {{WebExtAPIRef("permissions.Permissions")}} object.

The permissions requested must be listed in the extension's:

• optional_permissions key of its manifest.json file for origins and permissions. The origins property can include permissions matching a subset of the hosts matched by an optional permission. For example, if optional_permissions include "*://mozilla.org/", then permissions.origins can include "https://developer.mozilla.org/".
• gecko.data_collection_permissions.optional property of the browser_specific_settings key of its manifest.json file for data_collection.

Requests for optional-only permissions can't include any other optional permissions.

The extension can only make the request inside the handler for a user action. Unless the browser can grant all the requested permissions silently, it prompts the user to grant them. The browser makes one request for all requested permissions: either all are granted, or none are.

The extension retains any permissions granted, even over upgrade and disable and enable cycling.

Syntax

let requesting = browser.permissions.request(
  permissions                // Permissions object
)

Parameters

• permissions
  • : A {{WebExtAPIRef("permissions.Permissions")}} object.

Return value

A Promise fulfilled with true if the browser grants the extension the permissions listed in the permissions argument, or false otherwise.

Examples

This code adds a click handler that prompts the user for various permissions, then logs the request's outcome and the extension's permissions after the request completes.

const permissionsToRequest = {
  permissions: ["bookmarks", "history"],
  origins: ["https://developer.mozilla.org/"],
};

async function requestPermissions() {
  function onResponse(response) {
    if (response) {
      console.log("Permission was granted");
    } else {
      console.log("Permission was refused");
    }
    return browser.permissions.getAll();
  }

  const response = await browser.permissions.request(permissionsToRequest);
  const currentPermissions = await onResponse(response);

  console.log(`Current permissions:`, currentPermissions);
}

document
  .querySelector("#request")
  .addEventListener("click", requestPermissions);

{{WebExtExamples}}

Browser compatibility

{{Compat}}

[!NOTE] This API is based on Chromium's chrome.permissions API.