Permissions API
Lets a page ask what each permission is currently set to without prompting.
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
| Browser | Status | First version | Released | Note |
|---|---|---|---|---|
| Chrome | Supported | 43 | 2015-05-19 | None |
| Edge | Supported | 79 | 2020-01-15 | None |
| Firefox | Supported | 46 | 2016-04-26 | Not all names supported |
| Safari | Supported | 16 | 2022-09-12 | None |
| Safari on iPhone | Supported | 16 | 2022-09-12 | None |
| Chrome on Android | Supported | 43 | 2015-05-27 | None |
| Samsung Internet | Supported | 4.0 | 2016-03-11 | None |
How a site asks for it
| API | navigator.permissions.query({name}); PermissionStatus.state; 'change' event |
| Browser compat keys | api.Permissions.queryapi.PermissionStatus |
| How access is granted | none |
| What the user sees | No prompt; read only. States: granted, denied, prompt. A permissions policy block reports denied. |
| Needs a secure context (HTTPS) | Yes |
| Needs a user gesture | No |
| How long it lasts | n/a |
| How to take it back | n/a |
| Inside an iframe | Works in iframes; reflects policy |
Typical flow
- Call permissions.query({name: 'geolocation'})
- Read status.state
- Listen to status.onchange
Data you get
What comes back: PermissionStatus
Shape: object
How often: on call plus change events
| Field | Type | Unit | Range | Precision |
|---|---|---|---|---|
state | enum | none | granted, denied, prompt | log2(3) bits per name |
names | string | text | about 25 names in Chromium | state 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
| Type | Example | Apps |
|---|---|---|
| video | A 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 |
| maps | A maps site only shows the Use my location button if location is not blocked. | Google Maps |
| games | A browser game asks for microphone access only if it has not been blocked, and shows tips otherwise. | None named |
| news | A news site waits to ask about notifications until it knows you have not blocked them. | None named |
| security | A fraud tool reads the pattern of allowed and blocked permissions as part of a device profile. | FingerprintJS |
| developer | A web app shows a status panel that lists which features are allowed. | None named |
| shopping | A 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
| Score | Value | Meaning |
|---|---|---|
| Sensitivity | 2 of 5 | How revealing the data is |
| Utility | 3 of 5 | How useful it is to honest apps |
| Friction | 0 of 5 | How much the user has to do |
| Fingerprint bits | 4 | Rough identifying entropy, when known |
History
- 2015-05, Chrome 43: Permissions API ships
- 2020-03, Safari 16: Permissions API ships
Related capabilities
Related
- Permissions Policy and iframe allow. Can turn features off for itself and its embedded frames
Sources
How well checked: Checked against real behavior.