JavaScript Document requestStorageAccess() Method

What You’ll Learn

document.requestStorageAccess() is an instance method that lets third-party embeds ask for access to unpartitioned cookies and related state (see MDN Document: requestStorageAccess()). Learn the Storage Access flow, user-gesture rules, optional types / StorageAccessHandle, pairing with hasStorageAccess(), and five try-it labs.

Introduction

Modern browsers often block third-party cookies and partition storage so trackers cannot quietly follow users across sites. Embedded widgets (chat, login, payment, comments) sometimes still need their own site’s cookies when shown inside an <iframe>.

MDN: requestStorageAccess() lets that embed request access to third-party cookies and unpartitioned state. It is part of the Storage Access API. First check with hasStorageAccess(); if access is missing, call requestStorageAccess() from a user gesture.

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

Understanding document.requestStorageAccess()

An instance method on Document (Storage Access API).

• Audience — third-party embedded content (MDN).
• Optional types — object selecting unpartitioned state (cookies, localStorage, indexedDB, …) (MDN).
• Return — a Promise: undefined on cookie grant without types; StorageAccessHandle when types is used; rejects on deny (MDN).
• Gesture — usually needs transient activation unless already granted (MDN).
• Secure context — required; otherwise NotAllowedError (MDN).
• After grant — reload the embed so unpartitioned cookies are included (MDN).
• Policy — may be blocked by a storage-access Permissions Policy (MDN).

📝 Syntax

General forms of Document.requestStorageAccess (MDN):

requestStorageAccess()
requestStorageAccess(types)

Parameters

• types Optional — an object controlling which unpartitioned state becomes accessible. Properties default to false when omitted. MDN lists flags such as all, cookies, sessionStorage, localStorage, indexedDB, locks, caches, getDirectory, estimate, createObjectURL, revokeObjectURL, BroadcastChannel, and SharedWorker.

Return value

A Promise that fulfills with undefined if third-party cookie access was granted and no types parameter was provided; fulfills with a StorageAccessHandle if types requested unpartitioned state; and rejects if access was denied (MDN).

Exceptions

• InvalidStateError DOMException — Document not yet active, or types is provided with all properties false (MDN).
• NotAllowedError DOMException — not a secure context, blocked by Permissions Policy, null origin, sandbox missing allow-storage-access-by-user-activation, or the user agent denies permission (MDN).

MDN basic samples

document.requestStorageAccess().then(
  () => {
    console.log("cookie access granted");
  },
  () => {
    console.log("cookie access denied");
  },
);

document.requestStorageAccess({ localStorage: true }).then(
  (handle) => {
    console.log("localStorage access granted");
    handle.localStorage.setItem("foo", "bar");
  },
  () => {
    console.log("localStorage access denied");
  },
);

⚖️ requestStorageAccess vs hasStorageAccess

Examples Gallery

Examples follow MDN Document: requestStorageAccess(). Labs show API shape on this page; real grants belong in third-party iframes under HTTPS.

const supported = typeof document.requestStorageAccess === "function";
console.log("requestStorageAccess:", supported);
console.log("secure context:", window.isSecureContext);

if (!supported) {
  console.log("Storage Access API not available here");
}

requestStorageAccess: true
secure context: true
(or false on older / insecure contexts)

if (typeof document.requestStorageAccess !== "function") {
  console.log("unsupported");
} else {
  document.requestStorageAccess().then(
    () => {
      console.log("cookie access granted");
    },
    () => {
      console.log("cookie access denied");
    },
  );
}

cookie access granted
(or cookie access denied / unsupported)

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

btn.addEventListener("click", async () => {
  if (typeof document.requestStorageAccess !== "function") {
    log.textContent = "unsupported";
    return;
  }
  try {
    await document.requestStorageAccess();
    log.textContent = "granted — reload embed in real iframes";
  } catch (err) {
    log.textContent = "denied: " + (err && err.name ? err.name : err);
  }
});

granted — reload embed in real iframes
(or denied: NotAllowedError)

async function ensureStorageAccess() {
  if (typeof document.hasStorageAccess !== "function") {
    return "hasStorageAccess unsupported";
  }
  if (await document.hasStorageAccess()) {
    return "already has access";
  }
  if (typeof document.requestStorageAccess !== "function") {
    return "requestStorageAccess unsupported";
  }
  try {
    await document.requestStorageAccess();
    return "granted";
  } catch (err) {
    return "denied";
  }
}

// Call ensureStorageAccess() from a click handler

already has access
(or granted / denied / unsupported)

document.requestStorageAccess({ localStorage: true }).then(
  (handle) => {
    console.log("localStorage access granted");
    handle.localStorage.setItem("foo", "bar");
    console.log(handle.localStorage.getItem("foo"));
  },
  () => {
    console.log("localStorage access denied");
  },
);

localStorage access granted
bar
(or localStorage access denied — support for types varies)

🚀 Common Use Cases

• Embedded login / SSO widgets — restore the embedder’s cookies inside an iframe (MDN use case).
• Chat / comment / payment embeds — personalized state blocked by default third-party cookie rules.
• Storage Access flow — check with hasStorageAccess(), then request on click (MDN).
• Unpartitioned storage — request localStorage / indexedDB via types where supported (MDN).
• Permission query UX — combine with Permissions.query({ name: "storage-access" }) (MDN).
• Post-grant reload — reload the embed so requests include unpartitioned cookies (MDN).

📝 Notes

• MDN: Baseline Widely available since December 2023; some parts may vary.
• Not Deprecated, Experimental, or Non-standard.
• Requires a secure context (HTTPS / localhost) (MDN).
• May be blocked by a storage-access Permissions Policy (MDN).
• Sandboxed iframes need allow-storage-access-by-user-activation (MDN).
• Related: hasStorageAccess(), hasUnpartitionedCookieAccess(), hasPrivateToken().

💡 Best Practices