Document: requestStorageAccessFor() method

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The requestStorageAccessFor() method of the Document interface allows top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same related website set. It returns a Promise that resolves if the access was granted, and rejects if access was denied.

Syntax

js
requestStorageAccessFor(requestedOrigin)

Parameters

requestedOrigin

A string representing the URL of the origin you are requesting third-party cookie access for.

Return value

A Promise that fulfills with undefined if the access to third-party cookies was granted and rejects if access was denied.

requestStorageAccessFor() requests are automatically denied unless the top-level content is currently processing a user gesture such as a tap or click (transient activation), or unless permission was already granted previously. If permission was not previously granted, they must run inside a user gesture-based event handler. The user gesture behavior depends on the state of the promise:

  • If the promise resolves (i.e., permission was granted), then the user gesture has not been consumed, so the script can subsequently call APIs requiring a user gesture.
  • If the promise is rejected (i.e., permission was not granted), then the user gesture has been consumed, so the script can't do anything that requires a gesture. This prevents scripts from calling requestStorageAccessFor() again if permission is denied.

Exceptions

InvalidStateError DOMException

Thrown if the current Document is not yet active.

NotAllowedError DOMException

Thrown if:

  • The document's window is not a secure context.
  • The document is not the top-level document.
  • The document has a null origin.
  • The supplied requestedOrigin is opaque.
  • The top-level and embedded sites are not in the same related website set.
  • The embedding <iframe> is sandboxed, and the allow-storage-access-by-user-activation token is not set.
  • Usage is blocked by a storage-access Permissions Policy.
  • Usage is denied by the user agent's permission request to use the API.
TypeError

Thrown if requestedOrigin is not a valid URL.

Description

The requestStorageAccessFor() method addresses challenges in adopting the Storage Access API on top-level sites that use cross-site images or scripts requiring cookies. It is relevant to user agents that by default block access to third-party, unpartitioned cookies to improve privacy (e.g. to prevent tracking), and is a proposed extension of the Storage Access API.

requestStorageAccessFor() can enable third-party cookie access for cross-site resources directly embedded into a top-level site that are unable to request storage access themselves, for example <img> elements. Cross-site content embedded in <iframe>s that has its own logic and resources and needs third-party cookie access should request storage access via Document.requestStorageAccess().

To check whether permission to access third-party cookies has already been granted via requestStorageAccessFor(), you can call Permissions.query(), specifying the feature name "top-level-storage-access". This is different from the feature name used for the regular Document.requestStorageAccess() method, which is "storage-access".

The Permissions.query() call must specify the embedded origin; for example:

js
navigator.permissions.query({
  name: "top-level-storage-access",
  requestedOrigin: "https://www.example.com",
});

Note: Usage of this feature may be blocked by a storage-access Permissions Policy set on your server (the same one that controls the rest of the Storage Access API). In addition, the document must pass additional browser-specific checks such as allowlists, blocklists, on-device classification, user settings, or anti-clickjacking heuristics.

Examples

js
function rSAFor() {
  if ("requestStorageAccessFor" in document) {
    document.requestStorageAccessFor("https://example.com").then(
      (res) => {
        // Use storage access
        doThingsWithCookies();
      },
      (err) => {
        // Handle errors
      },
    );
  }
}

After a successful requestStorageAccessFor() call, cross-site requests will include cookies if they include CORS / crossorigin, so sites may want to wait before triggering a request. Such requests must use the credentials: "include" option and resources must include the crossorigin="use-credentials" attribute.

For example:

js
function checkCookie() {
  fetch("https://example.com/getcookies.json", {
    method: "GET",
    credentials: "include",
  })
    .then((response) => response.json())
    .then((json) => {
      // Do something
    });
}

Note: See Using the Storage Access API for a more complete example.

Specifications

Specification
requestStorageAccessFor API
# dom-document-requeststorageaccessfor

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
requestStorageAccessFor
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.

See also