Permissions API: Browser Support, States, Limitations

What is the Permissions API?

The Permissions API is a JavaScript interface, edited by the W3C Web Application Security Working Group, that exposes permission state on navigator.permissions. A call to query returns a PermissionStatus object whose state is granted, denied, or prompt, and the object fires a change event when the user updates the setting.

Which browsers does the Permissions API support?

Every Chromium-based browser, Firefox, and Safari 16+ ship the Permissions API, putting global support near 96%. Internet Explorer and the legacy Android Browser left it out.

What permissions can you query with the Permissions API?

navigator.permissions.query accepts a PermissionDescriptor with a name field. Each browser ships its own subset of permission names, so feature-detect every name before relying on it.

• geolocation: Supported in Chrome, Edge, Firefox, Opera, Samsung Internet, and Safari 16+. The most consistent permission name across every engine and the safest default for cross-browser tests.
• notifications: Chrome, Edge, Firefox, Opera, and Samsung Internet support it on every platform. Safari 16+ accepts the name on macOS but the iOS implementation only returns a state for sites added to the home screen.
• camera and microphone: Chromium browsers and Safari 16+ accept these names. Firefox throws a TypeError because Mozilla has not exposed them through navigator.permissions; use mediaDevices.getUserMedia and catch NotAllowedError as a fallback.
• push: Chrome, Edge, Firefox, Opera, and Samsung Internet support it. Safari does not accept the push name because its push implementation is tied to web app manifests rather than the Permissions API.
• clipboard-read and clipboard-write: Chromium browsers only. Firefox and Safari throw a TypeError; for those engines fall back to async-clipboard feature detection.
• persistent-storage: Chrome, Edge, Firefox, Opera, and Samsung Internet. Safari does not accept it. Pair it with navigator.storage.estimate to plan offline storage flows.
• background-sync, screen-wake-lock, midi: Chromium browsers and Firefox subset support these. Safari does not accept them, so wrap each call in try/catch when you ship cross-browser code.
• local-fonts, window-management, compute-pressure: Recent Chromium-only names. Firefox and Safari throw a TypeError on every version, and they should be feature-detected behind a separate code path.
• storage-access: Chrome, Edge, Firefox, and Safari 16.4+ accept this name as part of the Storage Access API. It is the most reliable cross-browser way to check if first-party storage is available inside a third-party iframe.

How do you check if a browser supports the Permissions API?

Run a two-step check at runtime: confirm navigator.permissions exists, then call query with the permission name you care about and read result.state. Wrap query in try/catch because unknown names throw a TypeError on Safari and Firefox.

• Feature-detect navigator.permissions: Check for "permissions" in navigator before you call query, since older Safari and the legacy Android Browser skip the property entirely.
• Call navigator.permissions.query: Pass a descriptor with a name field, like the geolocation descriptor, and await the returned promise. The promise resolves with a PermissionStatus object.
• Read result.state: The PermissionStatus object exposes state as one of "granted", "denied", or "prompt". Map each state to UI behaviour without forcing a permission dialog.
• Listen for change events: Attach result.onchange so the UI reacts when the user updates the site setting from the address bar or the OS privacy panel.
• Catch TypeError for unsupported names: Safari throws when given names like push or clipboard-read, so wrap query in try/catch and fall back to the older feature-specific permission flow.

Paste the snippet below into the DevTools console. It walks four common names, prints the current state, and logs any change the user makes inside the same tab.

// Paste this into the DevTools console of any modern browser.
// It feature-detects navigator.permissions, then queries a few names safely.
async function checkPermissions() {
  if (!("permissions" in navigator)) {
    console.log("Permissions API is not supported in this browser.");
    return;
  }

  const names = ["geolocation", "notifications", "camera", "microphone"];
  for (const name of names) {
    try {
      const status = await navigator.permissions.query({ name });
      console.log(name + ":", status.state);

      status.onchange = () => {
        console.log(name + " changed to:", status.state);
      };
    } catch (err) {
      console.warn(name + " is not a recognised name in this browser:", err.message);
    }
  }
}

checkPermissions();

What are the known issues with the Permissions API?

The Permissions API ships in every modern engine, but the names, the worker surface, and the request flow drift across browsers. Plan around these gaps before you wire query into a production permission strategy.

• Permission names are not portable: Each browser ships its own subset, so a name that works in Chrome can throw a TypeError in Safari or Firefox. Always feature-detect each name with try/catch.
• Permissions.revoke is gone: Both Chrome and Firefox removed Permissions.revoke. Pages cannot programmatically clear a granted permission, so users have to revoke through site settings or by clearing site data.
• Querying does not request: query never prompts the user. To actually request camera or microphone you still call getUserMedia, and to request notifications you still call Notification.requestPermission.
• Safari subset is small: Safari 16+ accepts only camera, microphone, geolocation, and notifications. Push, clipboard, midi, and background-sync all throw TypeError, even on the latest macOS Sequoia and iOS 18 builds.
• Secure-context only for many names: camera, microphone, and clipboard names are gated to HTTPS or localhost. Plain http:// pages get a SecurityError when they try to query these names.
• Workers expose a different surface: WorkerNavigator.permissions is wired in Chromium and Firefox, but Safari does not expose navigator.permissions inside service workers. Plan permission checks on the main thread for cross-browser parity.
• "prompt" hides past denials: A "prompt" state can mean the user has not been asked or that an earlier denial expired. The API does not separate the two, so keep a server-side flag if you need that distinction.
• Iframe behaviour follows Permissions-Policy: Cross-origin iframes need a Permissions-Policy allowlist for camera, microphone, geolocation, and the other powerful names. Without the header the query state silently degrades to denied.

In my experience, the most surprising failure is forgetting that query never prompts. Calling navigator.permissions.query for the camera name on page load and reading "prompt" tricks people into thinking the user has been asked, when in fact getUserMedia still has to fire the dialog later.

Citations

All Permissions API version numbers and platform notes in this guide come from these primary sources:

• MDN Web Docs - Permissions API: developer.mozilla.org/en-US/docs/Web/API/Permissions_API
• MDN Web Docs - Permissions interface: developer.mozilla.org/en-US/docs/Web/API/Permissions
• MDN Web Docs - Navigator.permissions: developer.mozilla.org/en-US/docs/Web/API/Navigator/permissions
• MDN Web Docs - Permissions.query(): developer.mozilla.org/en-US/docs/Web/API/Permissions/query
• MDN Web Docs - PermissionStatus: developer.mozilla.org/en-US/docs/Web/API/PermissionStatus
• W3C Permissions specification: w3.org/TR/permissions
• W3C Permissions editor's draft: w3c.github.io/permissions
• Chrome for Developers - Permissions API for the Web: developer.chrome.com/blog/permissions-api-for-the-web
• Chrome Platform Status - Permissions API: chromestatus.com/feature/6443143280984064
• Mozilla Specification Positions: mozilla.github.io/standards-positions
• WebKit Standards Positions: webkit.org/standards-positions
• Wikipedia - Permissions API: en.wikipedia.org/wiki/Permissions_API