1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
---
title: permissions
slug: Mozilla/Add-ons/WebExtensions/API/permissions
tags:
- API
- Add-ons
- Extensions
- NeedsTranslation
- Permissions
- Reference
- TopicStub
- WebExtensions
translation_of: Mozilla/Add-ons/WebExtensions/API/permissions
---
<div>{{AddonSidebar}}</div>
<div>Enables extensions to request extra permissions at runtime, after they have been installed.</div>
<div></div>
<p>Extensions need permissions to access more powerful WebExtension APIs. They can ask for permissions at install time, by including the permissions they need in the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> manifest.json key. The main advantages of asking for permissions at install time are:</p>
<ul>
<li>The user is only asked once, so it's less disruptive for them, and a simpler decision.</li>
<li>The extension can rely on the access to the APIs it needs, because if already running, the permissions have been granted.</li>
</ul>
<p>There is not yet a simple GUI, for users to view permissions of their installed WebExtension Add-ons. Users must use about:debugging, go to the Add-ons section, then use the "Manifest Url" link for this Add-on. This shows raw json, which includes a "permissions" block, showing the permissions used by this addon.</p>
<p>With the permissions API, an extension can ask for additional permissions at runtime. These permissions need to be listed in the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions">optional_permissions</a></code> manifest.json key. Note that some permissions are not allowed in <code>optional_permissions</code>. The main advantages of this are:</p>
<ul>
<li>The extension can run with a smaller set of permissions, except when it actually needs them.</li>
<li>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.</li>
<li>
<p>The extension may need <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permissions</a>, 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.</p>
</li>
</ul>
<div>To use the permissions API, decide which permissions your extension can request at runtime, and list them in <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions">optional_permissions</a></code>. After this, you can request any permissions that were included in <code>optional_permissions</code>. Requests may only be made in the handler for a user action (for example, a click handler).</div>
<div></div>
<div>For advice on designing your request for runtime permissions, to maximize the likelihood that users grant them, see <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Request_the_right_permissions#Request_permissions_at_runtime">Request permissions at runtime</a>.</div>
<h2 id="Types">Types</h2>
<dl>
<dt>{{WebExtAPIRef("permissions.Permissions")}}</dt>
<dd>Represents a set of permissions.</dd>
</dl>
<h2 id="Methods">Methods</h2>
<dl>
<dt>{{WebExtAPIRef("permissions.contains()")}}</dt>
<dd>Discover an extension's given set of permissions.</dd>
<dt>{{WebExtAPIRef("permissions.getAll()")}}</dt>
<dd>Get all the permissions this extension currently has.</dd>
<dt>{{WebExtAPIRef("permissions.remove()")}}</dt>
<dd>Give up a set of permissions.</dd>
<dt>{{WebExtAPIRef("permissions.request()")}}</dt>
<dd>Ask for a set of permissions.</dd>
</dl>
<h2 id="Event_handlers">Event handlers</h2>
<dl>
<dt>{{WebExtAPIRef("permissions.onAdded")}}</dt>
<dd>Fired when a new permission is granted.</dd>
<dt>{{WebExtAPIRef("permissions.onRemoved")}}</dt>
<dd>Fired when a permission is removed.</dd>
</dl>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{Compat("webextensions.api.permissions")}}</p>
<h2 id="See_also">See also</h2>
<ul>
<li><code>manifest.json</code> <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> property</li>
<li><code>manifest.json</code> <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions">optional_permissions</a></code> property</li>
</ul>
<p>{{WebExtExamples("h2")}}</p>
<div class="note"><strong>Acknowledgements</strong>
<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/permissions"><code>chrome.permissions</code></a> API.</p>
<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p>
</div>
|
