Wiki · Concept · Last reviewed June 25, 2026

Protocol Handlers

Protocol handlers let a website or installed web app register itself as a handler for selected URL schemes, turning a link such as mailto: or web+music: into a browser- or operating-system-mediated app launch.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser API, progressive web apps, URL schemes, installed web apps, agents, deep links

Definition

Protocol handlers are browser and operating-system registration mechanisms for routing non-HTTP URL schemes to an application. On the open web, there are two closely related paths: a page can call navigator.registerProtocolHandler(), or an installed web app can declare protocol_handlers in its Web App Manifest. Both create a handoff from a scheme URL to a handler URL, not a general permission to control that scheme everywhere.

MDN defines navigator.registerProtocolHandler() as a method that lets websites register their ability to open or handle URL schemes. The HTML Standard defines the custom scheme handler API on Navigator, constrains acceptable schemes and handler URLs, and says the handler URL uses %s as the placeholder for the URL being handled. The WICG Manifest Incubations draft defines protocol_handlers as an array of protocol handler descriptions that lets a web application handle URL protocols when installed.

Current Context

As of June 25, 2026, protocol handling remains a real but uneven web-platform surface. The HTML Standard defines the JavaScript registration model and security and privacy considerations. MDN marks navigator.registerProtocolHandler() as limited availability and not Baseline because it does not work in some widely used browsers. Manifest-based PWA protocol handling is specified in WICG Manifest Incubations, documented by MDN, Chrome, and Microsoft Edge, and depends on browser, installation, operating-system integration, and user approval behavior.

The practical rule is to treat protocol handlers as capability negotiation, not universal routing. A handler that works in one browser profile or operating system may not be registered, selected, or default in another. A governed system should therefore record both the declared handler and the observed launch outcome.

How It Works

A JavaScript registration calls navigator.registerProtocolHandler(scheme, url). The scheme can be a safelisted scheme such as mailto, tel, sms, webcal, or xmpp, or a custom scheme that starts with web+ followed by lowercase ASCII letters. The scheme argument does not include the colon. The registration must run in a secure context, and the handler URL must be same-origin, use HTTP(S), and include %s, which the user agent replaces with the encoded URL that triggered the handoff.

A manifest registration uses protocol_handlers, where each entry has a protocol string and a url string. WICG says the URL must be within the application's scope, and user agents should ask users for permission before registering protocol handlers as defaults with the host operating system. Chrome documentation describes protocol handler registration as part of PWA installation, with first-launch permission prompts and DevTools inspection. Microsoft Edge documentation shows the same manifest pattern and describes using the Application tool to verify and test registered protocol handlers.

Agent Context

For AI Browsers and Computer Use, protocol handling is a deep-link boundary. A link such as mailto:, web+music:, web+auth:, or another allowed scheme can move a user from a page, message, document, or native app into an installed web app. If that app contains an assistant, the encoded URL can become task context, identity context, routing context, or model input.

This is not the same as a normal hyperlink. The user may expect a trusted mail client, wallet, calendar, note taker, or internal workflow tool, while the browser may offer a registered web handler. The URL payload can also be attacker-controlled: a public web page, email, document, QR code, or chat message can construct a protocol link that becomes application input. An agent that follows or proposes protocol links should preserve who proposed the link, which handler was selected, and whether the resulting app context was fresh, authenticated, or already personalized.

Governance Use

A governed deployment should review each declared protocol before installing or recommending a PWA. The scheme should match the product's real role, the handler URL should be narrow and in scope, and the app should preview sensitive parameters before an agent acts. For internal schemes, policy should define who may register handlers, which schemes are reserved, how default-handler conflicts with native apps or other web apps are resolved, and how users can revoke or change the handler.

Agent platforms should treat protocol launches as ingress events. The encoded URL may contain account identifiers, message addresses, payment handles, internal ticket IDs, OAuth-like state, or prompt-like text. Before sending that content to a model, the app should apply data minimization, origin checks, parameter allowlists, and user-visible confirmation. High-impact actions such as sending messages, opening internal records, initiating payments, or changing account state should require a separate action gate after the handler opens.

Limits

Protocol handling is not a permission to do everything associated with a scheme. It routes a URL to an application or handler page. It does not prove that the selected handler is the user's intended handler, that the handler is exclusive, that parameters are safe, that a custom scheme has stable semantics across organizations, or that the app behind the handler is safe to automate. Browser and operating-system behavior also varies.

The HTML Standard's security and privacy notes warn about hostile handler metadata, hijacking defaults, private URL data leaking to an unexpected handler, registration spamming, and interface interference from long strings. Those risks matter more when an agent compresses the handoff into a short recommendation such as "open this link."

Minimum Evidence Record

For an agent-facing protocol handler, record the manifest URL or registration page, app id if present, origin, scheme, handler URL template, whether registration came from JavaScript or manifest, declared application scope, browser and platform tested, user approval state if available, default-handler state if known, triggering URL origin, encoded URL category, selected handler, launch surface, agent task identifier, downstream action gate, and any cancelled or rejected handoff. Store redacted payload categories or hashes when full URLs would expose private data.

Source Discipline

Use the HTML Standard and MDN for navigator.registerProtocolHandler(), handler URL templates, secure-context constraints, safelisted schemes, browser support warnings, and privacy notes. Use WICG Manifest Incubations for protocol_handlers processing, installation behavior, permission language, and scope rules. Use Chrome and Microsoft Edge documentation for installed-PWA implementation notes, prompts, DevTools verification, and testing workflows. Treat secondary tutorials as examples, not authority for support, security, or enterprise policy claims.

Spiralist Reading

Spiralism reads protocol handlers as doors hidden inside links. The scheme says "mail," "auth," "music," or "pay," but the actual handler may be a web app with accounts, storage, and agents behind it. The humane pattern is explicit handoff: name the door, name who registered it, and show the payload before machinery interprets it.

Sources

Return to Wiki