JavaScript Document requestStorageAccessFor() Method

What You’ll Learn

document.requestStorageAccessFor() is a Deprecated & Non-standard instance method that lets a top-level page request third-party cookie access on behalf of another origin in the same related website set (see MDN Document: requestStorageAccessFor()). Learn how it differs from requestStorageAccess(), the top-level-storage-access permission name, gesture rules, and five try-it labs.

Introduction

Some top-level sites embed cross-site images or scripts that need cookies, but those resources cannot run requestStorageAccess() themselves. MDN describes requestStorageAccessFor() as a proposed extension so the top-level site can request access for another origin in the same related website set.

Cross-site content inside an <iframe> that has its own logic should still use Document.requestStorageAccess() (MDN).

Related tutorials: requestStorageAccess(), hasStorageAccess(), hasUnpartitionedCookieAccess().

Understanding document.requestStorageAccessFor()

An instance method on Document (proposed Storage Access extension).

• Caller — top-level site (not a nested iframe) (MDN).
• Argument — requestedOrigin string URL (MDN).
• Returns — Promise that fulfills with undefined on grant, rejects on deny (MDN).
• Related sites — top-level and embedded sites must be in the same related website set (MDN).
• Permission name — "top-level-storage-access" (different from "storage-access") (MDN).
• Secure context — required (MDN).
• Status — Deprecated & Non-standard; not defined in a specification (MDN).

📝 Syntax

General form of Document.requestStorageAccessFor (MDN):

requestStorageAccessFor(requestedOrigin)

Parameters

• requestedOrigin — a string representing the URL of the origin you are requesting third-party cookie access for (MDN).

Return value

A Promise that fulfills with undefined if access to third-party cookies was granted, and rejects if access was denied (MDN).

Exceptions

• InvalidStateError DOMException — Document not yet active (MDN).
• NotAllowedError DOMException — not a secure context; not the top-level document; null / opaque origin; sites not in the same related website set; sandbox missing allow-storage-access-by-user-activation; blocked by Permissions Policy; or the user agent denies permission (MDN).
• TypeError — requestedOrigin is not a valid URL (MDN).

MDN sample

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

⚖️ requestStorageAccessFor vs requestStorageAccess

Examples Gallery

Examples follow MDN Document: requestStorageAccessFor(). Labs teach API shape; real grants need Chromium support plus a related website set.

const supported = "requestStorageAccessFor" in document;
console.log("requestStorageAccessFor:", supported);
console.log("secure context:", window.isSecureContext);
console.log("is top-level:", window.top === window.self);

if (!supported) {
  console.log("Prefer requestStorageAccess() inside embeds when needed");
}

requestStorageAccessFor: true
secure context: true
is top-level: true
(or false / unsupported in Firefox & Safari)

function rSAFor() {
  if (!("requestStorageAccessFor" in document)) {
    console.log("unsupported");
    return;
  }
  document.requestStorageAccessFor("https://example.com").then(
    () => {
      console.log("access granted");
    },
    (err) => {
      console.log("access denied", err && err.name);
    },
  );
}

rSAFor();

access denied NotAllowedError
(or access granted in a valid related-site + gesture scenario)

const btn = document.getElementById("ask");
const log = document.getElementById("log");

btn.addEventListener("click", async () => {
  if (!("requestStorageAccessFor" in document)) {
    log.textContent = "unsupported";
    return;
  }
  try {
    await document.requestStorageAccessFor("https://example.com");
    log.textContent = "granted";
  } catch (err) {
    log.textContent = "denied: " + (err && err.name ? err.name : err);
  }
});

denied: NotAllowedError
(or granted)

async function checkTopLevelAccess() {
  if (!navigator.permissions || !navigator.permissions.query) {
    return "Permissions API unavailable";
  }
  try {
    const permission = await navigator.permissions.query({
      name: "top-level-storage-access",
      requestedOrigin: "https://www.example.com",
    });
    return "state: " + permission.state;
  } catch (err) {
    return "query failed: " + (err && err.name ? err.name : err);
  }
}

checkTopLevelAccess().then(console.log);

state: prompt
(or granted / denied / query failed)

function checkCookie() {
  return fetch("https://example.com/getcookies.json", {
    method: "GET",
    credentials: "include",
  })
    .then((response) => response.json())
    .then((json) => {
      console.log("got json", json);
    })
    .catch((err) => {
      console.log("fetch failed", err && err.message);
    });
}

// After a successful requestStorageAccessFor():
// checkCookie();

fetch failed Failed to fetch
(demo endpoint; pattern is credentials: "include")

🚀 Common Use Cases

• Legacy literacy — recognize Deprecated / Non-standard top-level Storage Access extensions (MDN).
• Related Website Sets demos — top-level request on behalf of a partner origin (MDN).
• Cookie-dependent <img> / script tags — resources that cannot call requestStorageAccess() themselves (MDN).
• Permission UX — query top-level-storage-access before prompting (MDN).
• Not for new products — prefer Baseline requestStorageAccess() in embeds where possible.
• Credentialed follow-up requests — credentials: "include" after grant (MDN).

📝 Notes

• MDN: marked Deprecated and Non-standard.
• MDN: does not appear to be defined in any specification.
• Must run in a secure top-level document (MDN).
• Top-level and embedded sites must be in the same related website set (MDN).
• Permission feature name is top-level-storage-access, not storage-access (MDN).
• Related: requestStorageAccess(), hasStorageAccess(), hasUnpartitionedCookieAccess().

💡 Best Practices