Document: requestStorageAccess() method

Baseline 2023

Newly available

Since December 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

The requestStorageAccess() method of the Document interface allows content loaded in a third-party context (i.e., embedded in an <iframe>) to request access to third-party cookies. This is relevant to user agents that, by default, block access to third-party, unpartitioned cookies to improve privacy (e.g., to prevent tracking), and is part of the Storage Access API.

To check whether permission to access third-party cookies has already been granted, you can call Permissions.query(), specifying the feature name "storage-access".

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.

Syntax

js
requestStorageAccess()

Parameters

None.

Return value

A Promise that fulfills with undefined if the access to third-party 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:

  • The document's window is not a secure context.
  • Usage is blocked by a storage-access Permissions Policy.
  • The document or the top-level document has a null origin.
  • The embedding <iframe> is sandboxed, and the allow-storage-access-by-user-activation token is not set.
  • Usage is denied by the user agent's permission request to use the API.

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