JavaScript Document hasStorageAccess() Method

What You’ll Learn

document.hasStorageAccess() is an instance method that returns a Promise resolving to whether this document can use third-party, unpartitioned cookies (see MDN Document: hasStorageAccess()). Learn the Storage Access API flow, when to call requestStorageAccess(), and important accuracy caveats.

Introduction

Embedded widgets (login buttons, comment tools, payment frames) often need their own cookies while living inside another site. Browsers increasingly partition or block that access. The Storage Access API lets embeds check and request permission.

MDN: hasStorageAccess() returns a Promise that resolves with a boolean indicating whether the document has access to third-party, unpartitioned cookies.

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

Understanding document.hasStorageAccess()

An instance method on the Document interface from the Storage Access API (MDN). It takes no arguments and returns a Promise<boolean>.

• No parameters — call it with empty parentheses (MDN).
• Return value — a Promise that resolves to true or false (MDN).
• Meaning — whether the document has access to third-party, unpartitioned cookies (MDN).
• Alias — another name for hasUnpartitionedCookieAccess() (MDN).
• Next step — if false, you may call requestStorageAccess() (MDN).
• User gesture note — if a user gesture was active when you called it, the resolve handler can still call APIs that need user activation (MDN).

📝 Syntax

General form of Document.hasStorageAccess (MDN):

hasStorageAccess()

Parameters

None (MDN).

Return value

A Promise that resolves with a boolean value indicating whether the document has access to third-party cookies — true if it does, and false if not (MDN).

Exceptions

• InvalidStateError — thrown if the current Document is not yet active (MDN).

MDN quick sample

document.hasStorageAccess().then((hasAccess) => {
  if (hasAccess) {
    // storage access has been granted already.
    console.log("cookie access granted");
  } else {
    // storage access hasn't been granted already;
    // you may want to call requestStorageAccess().
    console.log("cookie access denied");
  }
});

⚖️ hasStorageAccess vs requestStorageAccess

Examples Gallery

Examples follow MDN Document: hasStorageAccess() and practical Storage Access patterns.

document.hasStorageAccess().then((hasAccess) => {
  if (hasAccess) {
    console.log("cookie access granted");
  } else {
    console.log("cookie access denied");
  }
});

cookie access granted
(or cookie access denied in restricted embeds)

async function checkAccess() {
  const hasAccess = await document.hasStorageAccess();
  return hasAccess ? "granted" : "denied";
}

checkAccess().then(console.log);

granted

async function run() {
  if (typeof document.hasStorageAccess !== "function") {
    console.log("Storage Access API missing — handle cookies defensively");
    return;
  }
  console.log("hasAccess:", await document.hasStorageAccess());
}

run();

hasAccess: true

async function ensureAccess() {
  if (typeof document.hasStorageAccess !== "function") {
    return "unsupported";
  }

  if (await document.hasStorageAccess()) {
    return "already granted";
  }

  if (typeof document.requestStorageAccess !== "function") {
    return "cannot request";
  }

  try {
    await document.requestStorageAccess();
    return "granted after request";
  } catch (err) {
    return "request denied: " + err.name;
  }
}

// Often call this from a button click (user gesture)

already granted
(or request flow result in embeds)

async function diagnose() {
  const apiSays = typeof document.hasStorageAccess === "function"
    ? await document.hasStorageAccess()
    : null;

  let cookieReadable = false;
  try {
    // Write+read a short-lived test cookie when allowed by your app policy
    document.cookie = "sa_probe=1; path=/; SameSite=None; Secure";
    cookieReadable = document.cookie.includes("sa_probe=");
  } catch (err) {
    cookieReadable = false;
  }

  return { apiSays, cookieReadable };
}

diagnose().then(console.log);

{ apiSays: true, cookieReadable: true }
(depends on browser cookie policy)

🚀 Common Use Cases

• Embedded login widgets — check cookie access before showing a signed-in state.
• Comment / chat embeds — decide whether to request storage access.
• Payment / identity iframes — gate features on unpartitioned cookie access.
• Defensive UX — invite users to sign in again when cookies fail despite true (MDN).
• Alias awareness — recognize hasUnpartitionedCookieAccess() as the same idea (MDN).
• Gesture-aware flows — request access from a button after a false check.

📝 Notes

• MDN: Baseline Widely available since December 2023.
• MDN: part of the Storage Access API.
• MDN: alias of hasUnpartitionedCookieAccess(); no current plan to remove this name.
• MDN: result can be inaccurate under some browser/user settings — handle cookie failures.
• MDN: InvalidStateError if the Document is not yet active.
• Related: hasRedemptionRecord(), hasUnpartitionedCookieAccess(), hasPrivateToken().

💡 Best Practices