> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions and host permissions

> Design least-privilege permission sets for your extension. Covers required, optional, and host permissions to improve user trust and review outcomes.

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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

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

* Keep one manifest accurate in [manifest.json](/docs/implementation-guide/manifest-json).
* Review page access in [Web-accessible resources](/docs/implementation-guide/web-accessible-resources).
* Validate boundary handling in [Messaging](/docs/implementation-guide/messaging).
* Do a release pass with [Security checklist](/docs/workflows/security-checklist).
* Compare `permissions` vs `host_permissions` behavior in [Manifest V3 troubleshooting](/docs/concepts/manifest-v3).