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. 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 with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Document.hasStorageAccess()`, `Document.requestStorageAccessFor()`
* Using the Storage Access API
* Introducing Storage Access API (WebKit blog)