Skip to Content
Platform.Ontology

Permissions API

Lets a page ask what each permission is currently set to without prompting.

Works without askingDevice detailsPermissionsWeb browsersWhile you use it

In one line

Can check whether you allowed or blocked a feature, without asking you

Lets a page ask what each permission is currently set to without prompting.

navigator.permissions.query() returns granted, denied or prompt for most permissions. It reveals which permissions you have granted or blocked, and a change event lets pages react live.

What it can and can't do

What the user does: Nothing. It happens when the page checks a setting

It can

  • See if a permission is allowed, blocked, or still to be asked
  • Skip a pop up if you already said no
  • Update the page if you change a setting
  • Learn which sensors you have allowed on that site

It cannot

  • Change a permission for you
  • See your choices for other sites
  • Turn a feature on without your yes
  • See states for every feature; some names are not supported

Browser support

BrowserStatusFirst versionReleasedNote
ChromeSupported432015-05-19None
EdgeSupported792020-01-15None
FirefoxSupported462016-04-26Not all names supported
SafariSupported162022-09-12None
Safari on iPhoneSupported162022-09-12None
Chrome on AndroidSupported432015-05-27None
Samsung InternetSupported4.02016-03-11None

How a site asks for it

APInavigator.permissions.query({name}); PermissionStatus.state; 'change' event
Browser compat keysapi.Permissions.query
api.PermissionStatus
How access is grantednone
What the user seesNo prompt; read only. States: granted, denied, prompt. A permissions policy block reports denied.
Needs a secure context (HTTPS)Yes
Needs a user gestureNo
How long it lastsn/a
How to take it backn/a
Inside an iframeWorks in iframes; reflects policy

Typical flow

  1. Call permissions.query({name: 'geolocation'})
  2. Read status.state
  3. Listen to status.onchange

Data you get

What comes back: PermissionStatus
Shape: object
How often: on call plus change events

FieldTypeUnitRangePrecision
stateenumnonegranted, denied, promptlog2(3) bits per name
namesstringtextabout 25 names in Chromiumstate vector across permissions

Technical limits

  • Names vary per browser
  • Permissions.revoke() was removed
  • Firefox lacks several names such as clipboard-read

The story

What it is

Lets a page check whether you already allowed, blocked or never answered a permission, without asking.

For you

You never see it. The page just looks at your earlier answers and decides whether to show a pop-up or a helpful button. It can also see when you change your answer later.

For makers

Asking for a permission at the wrong time annoys people and gets denied for good. The API lets sites ask only when it makes sense, and show a help message when the answer is blocked. It also reveals your settings, which can be used in a fingerprint.

Where you see it

TypeExampleApps
videoA video call page checks if the camera is already allowed and skips straight to the call, or shows a how-to-unblock note.Google Meet, Zoom
mapsA maps site only shows the Use my location button if location is not blocked.Google Maps
gamesA browser game asks for microphone access only if it has not been blocked, and shows tips otherwise.None named
newsA news site waits to ask about notifications until it knows you have not blocked them.None named
securityA fraud tool reads the pattern of allowed and blocked permissions as part of a device profile.FingerprintJS
developerA web app shows a status panel that lists which features are allowed.None named
shoppingA store locator checks location permission before showing a nearby stores prompt.None named

Risks

  • Shows your choices to sites
  • Adds to a fingerprint

What the platform says

  • MDN: Permissions API. Docs describe it as a way for pages to check permission status before asking.

Good uses and abuse

Legitimate uses

  • Hide unavailable buttons

Known abuse

  • Fingerprint by permission state vector

Scores

ScoreValueMeaning
Sensitivity2 of 5How revealing the data is
Utility3 of 5How useful it is to honest apps
Friction0 of 5How much the user has to do
Fingerprint bits4Rough identifying entropy, when known

History

  • 2015-05, Chrome 43: Permissions API ships
  • 2020-03, Safari 16: Permissions API ships

Sources

How well checked: Checked against real behavior.

On this page