#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 user trust, reduces review friction, and keeps features easier to reason about.

#Permission strategy

#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 a feature is not required for the first-run experience, 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

#Common mistakes

• Using broad wildcards like <all_urls> when only one or two origins are needed.
• Mixing host_permissions into a feature that could instead use a narrower user-triggered workflow.
• Forgetting that content scripts, WAR access, and programmatic injection 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.

#Related pages

• 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.