Skip to main content
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

NeedPrefer
Core API access required for the extension to functionpermissions
Host access required on installhost_permissions
Capability you can request lateroptional_permissions
Domain access that only some users needoptional_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

FeatureUsually involves
Content-script enhancement on a known sitehost_permissions for that site, sometimes scripting
Popup or options UI onlyoften no host permissions at all
Programmatic injectionscripting plus matching host permissions
Cross-tab workflowstabs and sometimes activeTab
Persisted settingsstorage
Notifications or badgesnotifications, 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

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

​
Next steps