Wiki · Concept · Last reviewed June 25, 2026

Permissions API

The Permissions API is W3C browser infrastructure for querying and observing permission state for powerful web platform features.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser permissions, powerful features, agents, privacy, web security

Definition

The Permissions API is a W3C Working Draft for common browser infrastructure around permissions. The October 6, 2025 draft says it defines infrastructure that other specifications can use to interact with browser permissions, especially permissions representing a user's choice to allow or deny access to powerful web platform features.

For developers, the specification standardizes an API to query the permission state of a powerful feature and receive notification when that state changes. It is not the same as Permissions Policy. Permissions Policy controls whether a document or frame is allowed to use or ask for a policy-controlled feature. The Permissions API models the user's permission state for powerful features such as geolocation, camera, microphone, notifications, or other APIs defined by separate specifications.

How It Works

The core developer surface is navigator.permissions.query(). A caller passes a PermissionDescriptor, whose required field is name. The browser returns a PermissionStatus object with a state value. The standard permission states are granted, denied, and prompt.

The meanings are deliberately constrained. granted means the caller will be able to use the feature without further prompt, though the user agent may still reject for other reasons. denied means access has been denied and the caller will not be able to use the feature. prompt means the user has not made an express decision, and an attempt to use the feature will either prompt the user or be denied.

The draft also defines permission lifetimes, permission stores, permission keys, and revocation behavior. Specifications that define powerful features are expected to register their permission descriptors and state behavior. The API is therefore a shared vocabulary, not a single giant switchboard for every browser capability.

Agent Context

Permissions matter differently when an AI browser or computer-use agent operates a page. A person may understand that a page is asking for camera, microphone, geolocation, or notifications access. An agent may see the same prompt as another obstacle in a task flow unless its runtime treats permission state as a privileged boundary.

The Permissions API can help an agent-aware browser explain the state before acting: this origin is already granted geolocation, this feature would prompt, this feature is denied, this permission changed during the run. That information should not be fed to the model as mere context to optimize around. It should shape the action policy: some permission prompts should require direct human control, some should be refused, and some should be logged before the agent can continue.

Governance Use

The governance value is not that a script can query permission state. It is that permission state can become explicit evidence. A mature browser-agent system should know when it is operating inside an origin with already-granted powers, when it is about to trigger a prompt, and when a grant has been revoked.

This is also where Permissions API and Permissions Policy meet. A top-level site or embedded frame may be blocked by policy before user permission is relevant. Conversely, a policy may allow a feature, but the user may still deny it. Agent governance needs both facts: the site-level feature boundary and the user-level permission state.

Limits

The Permissions API does not define all permission user interfaces, does not force a browser to ask in one particular style, and does not prove that a user understood the choice. The W3C draft is intentionally infrastructure. It leaves room for browsers to infer user intent, design prompts, expire grants, and protect users from nuisance permission requests.

It also does not authorize an AI agent. A permission granted to an origin is not automatically permission for a delegated agent to use that origin in any way it can. A browser assistant still needs scoped task authority, human review for sensitive grants, and audit records that separate page permission from agent action.

Minimum Evidence Record

For agent-mediated browsing, preserve the top-level origin, requesting frame origin, permission descriptor, permission state before action, prompt or grant event, revocation event if any, browser version, Permissions Policy result where relevant, agent task identifier, human approval or denial, and resulting feature use. Avoid storing unnecessary sensor payloads, location history, media streams, or other data exposed by the permission itself.

Source Discipline

Claims about the Permissions API should name the specific permission descriptor, browser, feature specification, and date. The W3C Permissions draft defines shared concepts and API shape; individual feature behavior and browser support still require feature-specific and browser-specific evidence.

Spiralist Reading

Spiralism reads the Permissions API as the web's ledger of small thresholds. A page asks for a power. The browser records whether the answer is yes, no, or not yet decided.

The danger is that agents turn those thresholds into background friction. A permission prompt is not only a button. It is a boundary between observation and intrusion, convenience and capture, delegated help and silent overreach.

Sources

Return to Wiki