Solved: Only permissions specified in the manifest may be requested

If you are using the new optional permission API (chrome.permissions) you may have run into “Only permissions specified in the manifest may be requested” exception when requesting a permission at runtime. This is caused by missing a matching permission in the extension manifest. Permissions API only allows to request permissions that have already been declared in the manifest as optional. This makes sense, because otherwise an extension could keep requesting more and more permissions from the user without declaring use-cases during the extension review process.

// Gets called when new permissions are added
​​chrome.permissions.onAdded.addListener((ev) => {
    console.log(`Permissions added: [${ev.permissions}] with origins [${ev.origins}]`);
});

chrome.action.onClicked.addListener(async tab => {
    // Requests optional permission to manage user downlods/download files
    chrome.permissions.request({ permissions: ["downloads"] }, (granted) => {
        console.log(`Permission was granted: ${granted}`);
    });
});

// manifest.json
"optional_permissions": [
     "downloads"
],

Permission origin

Optional permissions can be requested per origin. Similarly to the requirement to pre-define all optional permissions in the manifest, you also need to specify which origins your extension will use to request optional permissions. If you don’t know which origins you will need beforehand, you can use a wildcard host.

Code below will also throw “Only permissions specified in the manifest may be requested.” exception if you don’t specify matching host in host_permissions property.

chrome.permissions.request({ permissions: ["downloads"], origins: ["https://www.extension.ninja/"] }, (granted) => {
    console.log(`Permission was granted: ${granted}`);
});

// manifest.json
"host_permissions": [
    "*://*/"
],

Benefits of optional permissions

There is one big benefit to request permissions at runtime. Adding new optional permissions does not disable your extension in users’ browsers after an update. This is usually a big churn moment where you can lose many users, because users don’t understand why the extension is disabled or why new permissions are required.

Requesting new permissions at runtime also allows you to do it with more context and explain to users what value they will get by approving the permission.

You can discover other useful methods in chrome.permissions namespace on the official extension docs site.