Wiki · Concept · Last reviewed July 10, 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 handoff to an application.

Category: Concept Published: June 25, 2026 Modified: July 10, 2026 Last reviewed: July 10, 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 selected URI or 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.

The important boundary is app selection. A protocol link names a scheme, but the user agent and operating system decide which registered handler, if any, receives it. The handler receives the original protocol URL as data through a template containing %s. That means protocol handling is both a launch surface and an input surface.

The IANA URI Schemes registry records many permanent, provisional, and historical URI schemes. Web protocol-handler APIs are narrower: the HTML Standard constrains which schemes can be registered through the web API and constrains the handler URL, while the WICG Manifest Incubations draft applies the same validity rules to installed web app declarations.

Standards Boundary

There are three layers that should not be collapsed. First, RFC 3986 defines generic URI syntax and delegates scheme-specific semantics to each scheme specification. Second, RFC 7595 and the IANA registry define how URI schemes are registered, reviewed, and categorized. Third, browser APIs decide which scheme links a web page or installed web app may ask to handle.

RFC 7595 is especially useful for governance. It says a scheme name is not itself a protocol, even though it often identifies a protocol or application; it also says a scheme definition should describe its default operation and that default invocation should be safe. In practice, opening a protocol link should not by itself send a message, spend money, accept a contract, authorize an account change, or start an irreversible workflow.

The web+ convention is a web-platform escape hatch, not a globally governed private namespace. It reduces collision with built-in schemes, but it does not prove ownership, certification, trust, or stable semantics. For organization-specific or cross-product schemes, policy should document the owner, intended meaning, collision strategy, revocation path, and whether IANA registration or a different standards path is appropriate.

Current Context

As of the July 10, 2026 review, protocol handling remains a real but uneven web-platform surface. The HTML Standard is a living standard and defines the JavaScript registration model, scheme normalization, handler URL normalization, security and privacy considerations, and user-agent automation hooks. MDN marks navigator.registerProtocolHandler() as limited availability because it does not work in some widely used browsers.

Manifest-based PWA protocol handling is still specified through WICG Manifest Incubations rather than the core W3C Web App Manifest recommendation. MDN also marks the manifest protocol_handlers member as limited availability and experimental. Chrome says the feature is available from Chrome 96 for installed PWAs, while Microsoft Edge documents the same manifest pattern and DevTools test workflow. That is implementation evidence, not a cross-browser guarantee.

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, including whether the browser showed a prompt, whether the operating system showed a picker, and whether the selected handler was the one the user or policy expected.

How It Works

A JavaScript registration calls navigator.registerProtocolHandler(scheme, url). The scheme can be a safelisted scheme such as bitcoin, geo, magnet, mailto, matrix, sms, tel, 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. When a manifest-declared protocol handler is invoked, the browser should launch the web application with the computed result URL rather than merely navigating an ordinary tab.

Implementation details are browser-specific. Chrome documentation describes protocol handler registration as part of PWA installation, first-launch permission prompts, operating-system pickers when multiple apps handle the same scheme, manifest-update synchronization, and DevTools inspection. Microsoft Edge documentation shows the same manifest pattern and describes using the Application tool to verify and test registered protocol handlers. Those implementation notes are useful for Chromium-family deployments, but they should not be cited as universal browser behavior.

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. That makes protocol handlers adjacent to Prompt Injection whenever the handler passes URL contents into model context.

An agent that follows or proposes protocol links should preserve who proposed the link, which handler was selected, whether the selected handler was native or web-based, and whether the resulting app context was fresh, authenticated, already personalized, or tied to a previous task. If the launch opens an installed app with a Service Worker, local storage, or account memory, the resulting context may be much richer than the visible link suggests. Handler payloads should be treated as untrusted data until parsed, validated, minimized, and bound to a user-confirmed task.

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, recovery codes, meeting links, file identifiers, or prompt-like text. Before sending that content to a model, the app should apply Data Minimization, origin checks, parameter allowlists, redaction, and user-visible confirmation. High-impact actions such as sending messages, opening internal records, initiating payments, accepting invitations, or changing account state should require a separate action gate after the handler opens. The scheme name is not that action gate.

Enterprise policy should treat handler registration like any other app-ingress capability. Review app identity, manifest URL, installation path, update behavior, handler conflicts, browser profile scope, operating-system default status, and incident rollback. The same review should cover adjacent installed-app launch surfaces such as Launch Handler API, File Handling API, and Web Share Target API.

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 hijacking web usage, hijacking defaults, private URL data leaking to an unexpected handler, registration spamming, hostile handler metadata, 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."

Protocol handlers also do not create a durable semantic contract for custom schemes. A web+auth: or web+pay: link may mean one thing in one organization and something else elsewhere. If a user or agent treats the scheme name as proof of trust, the scheme has become a branding surface rather than a security boundary. For authentication-sensitive flows such as native-app redirects, compare the scheme with the relevant identity or OAuth profile instead of assuming a custom URL scheme is unique or phishing-resistant.

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, triggering document or app class, encoded URL category, selected handler, launch surface, agent task identifier, downstream action gate, revocation path, and any cancelled or rejected handoff. For non-web+ or organization-specific schemes, also record the IANA registration status or internal owner, default operation, collision policy, and security review. Store redacted payload categories or hashes when full URLs would expose private data.

Failure Modes

Handler impersonation. A web app registers for a familiar scheme and users mistake it for a native mail, calendar, wallet, or enterprise workflow client.

Private URL leakage. A link contains private state, internal identifiers, account handles, or one-time tokens, and a handler outside the expected organization receives the full encoded URL.

Prompt payload launch. A hostile page or message encodes instructions in a protocol URL, and the receiving assistant treats the payload as task instruction rather than untrusted input.

Unsafe default invocation. Opening a scheme URL immediately performs a write, payment, message, or account change even though URI-scheme guidance treats safe default invocation as a design expectation.

Default drift. An operating system or browser profile changes the default handler, but the agent or user interface still assumes the previous handler.

Scheme squatting. A custom web+ scheme becomes meaningful inside one product ecosystem, then another app registers the same label with incompatible semantics.

Silent automation. An agent opens a protocol URL and the handler performs a write action without a second confirmation inside the target app.

Source Discipline

Use the HTML Standard for navigator.registerProtocolHandler(), handler URL templates, secure-context constraints, safelisted schemes, normalization, automation hooks, and privacy notes. Use MDN for developer-facing summaries and compatibility warnings. 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.

Use RFC 3986 for generic URI syntax and RFC 7595 for URI-scheme registration guidance, especially claims about scheme definitions, safe default invocation, private scheme collisions, and security or privacy considerations. Use the IANA URI Schemes registry when making claims about registered URI schemes in general, but do not confuse IANA registration with eligibility for web protocol-handler registration. 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.

Open Questions

Sources

Return to Wiki