Permissions and host permissions

Keep your extension capable without asking for more privilege than the feature requires. Extension.js compiles and validates your extension, but the browser still enforces permissions, host_permissions, and optional_* fields from manifest.json. Good permission design improves trust and reduces issues during store review.

Permission strategy

Need	Prefer
Core API access required for the extension to function	`permissions`
Host access required on install	`host_permissions`
Capability you can request later	`optional_permissions`
Domain access that only some users need	`optional_host_permissions`

Common patterns

Background-driven feature

Use permissions for the browser APIs you need and add only the host patterns required by the feature:

{
  "manifest_version": 3,
  "permissions": ["storage", "tabs", "scripting"],
  "host_permissions": ["https://example.com/*"]
}

Optional capability

If the first-run experience does not require a feature, keep it optional:

{
  "manifest_version": 3,
  "permissions": ["storage"],
  "optional_permissions": ["notifications"],
  "optional_host_permissions": ["https://api.example.com/*"]
}

Practical rules

Ask for API permissions only when the feature truly needs them.
Keep host_permissions scoped to the smallest working set of origins.
Prefer optional permissions for secondary or premium features.
Re-audit permissions whenever you add background actions, content-script injection, or remote API calls.

Permission design by feature type

Feature	Usually involves
Content-script enhancement on a known site	`host_permissions` for that site, sometimes `scripting`
Popup or options UI only	often no host permissions at all
Programmatic injection	`scripting` plus matching host permissions
Cross-tab workflows	`tabs` and sometimes `activeTab`
Persisted settings	`storage`
Notifications or badges	`notifications`, `action`-related manifest fields

Common mistakes

Using broad wildcards like <all_urls> when you only need one or two origins.
Mixing host_permissions into a feature that could instead use a narrower user-triggered workflow.
Forgetting that content scripts, web-accessible resources, and script injection via chrome.scripting all have different security implications.
Documenting permissions in feature docs without explaining why each permission exists.

Review checklist

List every user-facing feature.
Map each feature to the exact API and host permissions it needs.
Move non-core permissions to optional permissions where possible.
Remove stale permissions left over from old experiments.
Re-test install prompts and browser-store expectations after changes.

Next steps

Keep one manifest accurate in manifest.json.
Review page access in Web-accessible resources.
Validate boundary handling in Messaging.
Do a release pass with Security checklist.
Compare permissions vs host_permissions behavior in Manifest V3 troubleshooting.

Manifest.json compilation and output Extension messaging across contexts

⌘I

​Permission strategy

​Common patterns

​Background-driven feature

​Optional capability

​Practical rules

​Permission design by feature type

​Common mistakes

​Review checklist

​Next steps