Document: requestStorageAccess() method

The requestStorageAccess() method of the Document interface allows a document loaded in a third-party context (i.e. embedded in an <iframe>) to request access to unpartitioned cookies.

This is relevant to user agents that by default block access to unpartitioned cookies by sites loaded in a third-party context to improve privacy (e.g. to prevent tracking), and is part of the Storage Access API.

Note: Usage of this feature may be blocked by a storage-access Permissions Policy set on your server. In addition, the document must pass additional browser-specific checks such as allowlists, blocklists, on-device classification, user settings, anti-clickjacking heuristics, or prompting the user for explicit permission.

Note: The browser compatibility section provides an overview about the support status of the Storage Access API.

Syntax

js

requestStorageAccess()

Parameters

None.

Return value

A Promise that fulfills with undefined if the access to unpartitioned cookies was granted, and rejects if access was denied.

requestStorageAccess() requests are automatically denied unless the embedded 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 need to be 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. if permission was granted), then the user gesture has not been consumed, so the script can subsequently call APIs that require a user gesture.
  • If the promise rejects (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 is intentional protection against abuse — it prevents scripts from calling requestStorageAccess() in a loop until the user accepts the prompt.

Exceptions

InvalidStateError DOMException

Thrown if the current Document is not yet active.

NotAllowedError DOMException

Thrown if:

Examples

js

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

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

Specifications

Specification
The Storage Access API
# dom-document-requeststorageaccess

Browser compatibility

BCD tables only load in the browser

See also