Document: requestStorageAccess() method

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 and unpartitioned state. 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".

Syntax

requestStorageAccess()
requestStorageAccess(types)

Parameters

types Optional

An object containing properties that control what unpartitioned state is made accessible. If not specified, the default value of the property is false. Available properties are as follows:

all

A boolean specifying all possible unpartitioned states should be made accessible.

cookies

A boolean specifying third-party cookies should be made accessible.

sessionStorage

A boolean specifying StorageAccessHandle.sessionStorage should be made accessible.

localStorage

A boolean specifying StorageAccessHandle.localStorage should be made accessible.

indexedDB

A boolean specifying StorageAccessHandle.indexedDB should be made accessible.

locks

A boolean specifying StorageAccessHandle.locks should be made accessible.

caches

A boolean specifying StorageAccessHandle.caches should be made accessible.

getDirectory

A boolean specifying StorageAccessHandle.getDirectory() should be made accessible.

estimate

A boolean specifying StorageAccessHandle.estimate() should be made accessible.

createObjectURL

A boolean specifying StorageAccessHandle.createObjectURL() should be made accessible.

revokeObjectURL

A boolean specifying StorageAccessHandle.revokeObjectURL() should be made accessible.

BroadcastChannel

A boolean specifying StorageAccessHandle.BroadcastChannel() should be made accessible.

SharedWorker

A boolean specifying StorageAccessHandle.SharedWorker() should be made accessible.

Return value

A Promise that fulfills with undefined if the access to third-party cookies was granted and no types parameter was provided, fulfills with StorageAccessHandle if the access to unpartitioned state requested by the types parameter was provided, 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.
• The types parameter is provided and all of its properties are false.

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

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");
 },
);

Specifications

Browser compatibility

See also

• Document.hasStorageAccess(), Document.hasUnpartitionedCookieAccess(), Document.requestStorageAccessFor()
• Using the Storage Access API
• Introducing Storage Access API (WebKit blog)