Web App Origin Association file

Limited availabilityNot supported in Firefox (Desktop), Firefox (Android), Safari (macOS), Safari (iOS)Explainer

The Web App Origin Association file lets an origin confirm that a web app may include that origin in its extended scope. The origin serves the JSON file at /.well-known/web-app-origin-association.

How it works

The app manifest lists another origin in scope_extensions. That origin confirms the request by using the app’s manifest id as a top-level key in its association file. The optional scope member limits the accepted URL space on the confirming origin; the explainer defines / as its default.

Each side controls its own declaration. Removing either the manifest entry or the matching association-file entry removes the pair described by the explainer.

Warning

Chromium’s parser ignores an entry whose top-level key is not a valid URL and reports Associated app ignored. Manifest ID is not a valid URL. It also reports Associated app ignored, type object expected. when the value is not an object (Chromium parser source).

Examples

The first example shows the association file itself; the second keeps a normal cross-origin link available when display mode cannot establish whether association succeeded.

Confirming one app

This file confirms the app whose manifest id is https://app.example/id and limits its accepted scope on the confirming origin to /docs.

{
  "https://app.example/id": {
    "scope": "/docs"
  }
}

Serve the JSON from https://support.example/.well-known/web-app-origin-association, because the confirming origin owns the file.

Keeping navigation usable with display-mode

The display-mode media feature reports the display mode in which the app is shown. That value is not an association-success signal, so keep the ordinary link as the navigation path in both branches.

const link = document.createElement('a');
link.href = 'https://support.example/docs';
link.textContent = 'Open documentation';

if ('matchMedia' in globalThis && matchMedia('(display-mode: standalone)').matches) {
  link.dataset.surface = 'standalone';
} else {
  link.dataset.surface = 'browser-fallback';
}

document.body.append(link);

The fallback does not guess why the standalone query is false. It leaves the cross-origin URL available for the browser to navigate normally.

See also

• scope_extensions manifest member
• id manifest member
• Scope Extensions for Web App Manifest (GitHub)
• display-mode (MDN)

Specifications

Specification	Status
manifest: scope_extensions	Explainer

• Legend
• Yes
• Partial
• Flag
• No
• Unknown

Browser / Platform	Support	Versions	Confidence	Source	Notes
Chrome (Desktop)#	Yes	138	high	source	—
Chrome (Android)#	Yes	138	high	source	1
Edge (Desktop)#	Yes	138	high	source	2
Firefox (Desktop)#	No	—	high	source	3
Firefox (Android)#	No	—	high	source	45
Safari (macOS)#	No	—	high	source	6
Safari (iOS)#	No	—	high	source	78
Samsung Internet#	Yes	30.0	high	source	9
WebView (Android)#	Yes	138	high	source	10

1. Derived by browser-compat-data mirroring from Chrome.
2. Derived by browser-compat-data mirroring from Chrome.
3. No Firefox support is recorded in browser-compat-data.
4. No Firefox for Android support is recorded in browser-compat-data.
5. Derived by browser-compat-data mirroring from Firefox.
6. No Safari support is recorded in browser-compat-data.
7. No Safari on iOS support is recorded in browser-compat-data.
8. Derived by browser-compat-data mirroring from Safari.
9. Derived by browser-compat-data mirroring from Chrome Android.
10. Derived by browser-compat-data mirroring from Chrome Android.

Source data: /compatibility/manifest-scope-extensions.json · Global usage: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

Source: spec · MDN · Last verified 2026-10-03 · Confidence: high (computed from sources)