Document-Isolation-Policy

The HTTP Document-Isolation-Policy response header enables crossOriginIsolation for a document without requiring Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy deployment, granting access to APIs like SharedArrayBuffer on a per-document basis.

Table of Contents

Usage

APIs like SharedArrayBuffer and high-resolution timers are gated behind crossOriginIsolation because they enable high-precision timing attacks (Spectre). The traditional isolation model requires deploying both COOP (same-origin) and COEP (require-corp or credentialless) across the entire page and all embedded resources. This deployment burden prevents many applications from accessing these APIs. COOP breaks cross-origin popup communication needed for OAuth and payment flows, and COEP requires every third-party embed and subresource to opt in with CORS or CORP headers.

The Document-Isolation-Policy header provides an alternative path. A single header on the document response enables crossOriginIsolation by leveraging the browser's process isolation (out-of-process iframes) instead of requiring cascading header deployment across all embedded content. The browser places the document in a separate process, preventing cross-origin data from being accessible in the same address space.

Key advantages over the COOP + COEP model:

  • Per-document isolation. Each frame independently opts into isolation through its own response header. Embedded iframes do not need to support COEP.
  • Cross-origin popup communication. Documents with Document-Isolation-Policy open and communicate with cross-origin popups normally, preserving OAuth and payment flows.
  • No cascading requirements. Third-party ads, widgets, and iframes load without modification. Only the document requesting isolation needs the header.

The header implies Origin-Agent-Cluster. Isolated documents and non-isolated same-origin documents are placed in separate agent clusters, preventing synchronous DOM access between them. Cross-document communication remains available through postMessage.

The header uses Structured Fields syntax. The value is a token with an optional report-to parameter identifying a reporting endpoint for violation reports. The header only takes effect in secure contexts (HTTPS). Browsers lacking process isolation capabilities (such as WebView) grant logical isolation only, without access to the gated APIs.

The report-only variant, Document-Isolation-Policy-Report-Only, detects and reports violations without blocking resources, allowing gradual deployment testing.

Note

Document-Isolation-Policy is supported in Chromium-based browsers. Firefox and Safari have not published support signals.

Values

none

The default value. No isolation is applied. Cross- origin resources load without restriction, and the document does not receive crossOriginIsolation.

isolate-and-require-corp

Cross-origin subresources require explicit opt-in through CORS or Cross-Origin-Resource-Policy headers. Resources without the required headers are blocked. This provides the strictest isolation, matching the behavior of COEP: require-corp but scoped to the individual document.

isolate-and-credentialless

Cross-origin no-CORS requests are sent without credentials (cookies, HTTP authentication). Resources do not need CORS or CORP headers because credentialless requests cannot access personalized data. This is the easier deployment option, matching COEP: credentialless behavior.

Directives

report-to

The report-to parameter specifies the name of a reporting endpoint (configured via the Reporting-Endpoints header) receiving violation reports when subresource loads are blocked. Each report includes the blocked URL, resource destination, and disposition ("enforce").

Example

Enabling cross-origin isolation with credentialless mode. The document gains access to SharedArrayBuffer without requiring CORP headers on third-party resources.

Document-Isolation-Policy: isolate-and-credentialless

Strict isolation requiring CORP on all cross-origin subresources, with violation reporting.

Document-Isolation-Policy:
  isolate-and-require-corp; report-to="dip-reports"

A video conferencing application using SharedArrayBuffer for audio processing while maintaining popup-based OAuth flows.

HTTP/1.1 200 OK
Content-Type: text/html
Document-Isolation-Policy: isolate-and-credentialless
Reporting-Endpoints: dip="https://example.re/reports"

Takeaway

The Document-Isolation-Policy header enables crossOriginIsolation on a per-document basis by leveraging process isolation, bypassing the deployment complexity of COOP and COEP while preserving cross-origin popup communication and third-party embed compatibility.

See also

Last updated: March 6, 2026