JavaScript Document requestStorageAccess() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method

Definition

document.requestStorageAccess() lets content in a third-party context (typically an <iframe>) request access to third-party cookies and other unpartitioned state. It is part of the Storage Access API and returns a Promise.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.requestStorageAccess. Start with this line.

JavaScript
document.requestStorageAccess() / (types)
CallWhat it does
document.requestStorageAccess() / (types)Primary signature.
document.requestStorageAccess(...)Call with the arguments your case needs.

Built into the browser. Call requestStorageAccess(...) on document — no import required.

Library declarations
JavaScript
document.requestStorageAccess() / (types)

Parameters

ParameterDescription
typesOptional. Object choosing unpartitioned APIs (cookies, localStorage, …)

Return Value

Return ValueDescription
*Promise → undefined or StorageAccessHandle

JavaScript Examples

Example 1 — Basic Grant / Deny

MDN-style: request cookie access and log the outcome.

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

How It Works

  1. Call the method. It returns a Promise immediately.
  2. On fulfill. Cookie access was granted (no types → resolve value is undefined).
  3. On reject. Access was denied — log and show a fallback.
  4. Context matters. Top-level tutorial pages often deny; iframes + clicks are the real path.

Example 2 — Request from a User Click

Wire the call to a button so transient activation is present.

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

btn.addEventListener("click", async () => {
  if (typeof document.requestStorageAccess !== "function") {
    console.log("API missing");
    return;
  }
  try {
    await document.requestStorageAccess();
    console.log("granted — reload embed next");
    // location.reload();
  } catch (err) {
    console.log("denied:", err.name);
  }
});
Try It Yourself

How It Works

  1. Wait for a click. MDN: without a gesture (or prior grant), requests are denied.
  2. Feature-detect. Skip cleanly if the method is missing.
  3. Await the Promise. try/catch separates grant from deny.
  4. On grant, reload. MDN recommends reloading the embed so cookies are included.

Example 3 — Request localStorage via types

Pass a types object; on grant you receive a StorageAccessHandle.

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

How It Works

  1. Pass types. Ask only for the unpartitioned APIs you need.
  2. Receive a handle. On fulfill, MDN returns a StorageAccessHandle.
  3. Use the handle. e.g. handle.localStorage.setItem(...).
  4. All-false types throw. Providing types with every property false raises InvalidStateError (MDN).

Browser Support

Document.requestStorageAccess() is a browser DOM API marked Baseline Widely available on MDN (across browsers since December 2023). Some parts of the feature may have varying support.

✓ Baseline Widely available *

Document.requestStorageAccess()

Storage Access API — third-party embeds request unpartitioned cookies / state under privacy rules.

Baseline Widely available
Google Chrome Modern Storage Access support
Yes
Microsoft Edge Modern Storage Access support
Yes
Mozilla Firefox Modern Storage Access support
Yes
Apple Safari Modern Storage Access support
Yes
Opera Follow Chromium Storage Access
Yes
Internet Explorer No
No
requestStorageAccess() Strong in modern browsers

Bottom line: Available in current evergreen browsers; exact grant rules still depend on context, policy, and user settings. See the MDN Document.requestStorageAccess() reference.

Frequently Asked Questions

It lets content loaded in a third-party context (for example an iframe) request access to third-party cookies and unpartitioned state. It is part of the Storage Access API.
No. MDN marks it Baseline Widely available (across browsers since December 2023). Some parts may have varying support. It is not Deprecated, Experimental, or Non-standard.
Usually yes. Requests are automatically denied unless the embed is processing a user gesture (transient activation), or permission was already granted previously.
undefined if cookie access was granted and no types parameter was provided; a StorageAccessHandle if types requested unpartitioned state; the Promise rejects if access was denied.
Call document.hasStorageAccess() (or hasUnpartitionedCookieAccess()). You can also use Permissions.query() with the feature name "storage-access".
After an embed activates storage-access permission, it should reload itself so the browser re-requests the resource with third-party unpartitioned cookies included.

Next: requestStorageAccessFor()

Learn the related Storage Access helper used with another origin.

requestStorageAccessFor() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

10 people found this page helpful