# Document: requestStorageAccess() method



The **`requestStorageAccess()`** method of the [Document](https://developer.mozilla.org/en-US/docs/Web/API/Document) interface allows content loaded in a third-party context (i.e., embedded in an [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)) to request access to [third-party cookies](https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Third-party_cookies) and [unpartitioned state](https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/State_Partitioning#state_partitioning).
This is relevant to user agents that, by default, block access to third-party, [unpartitioned](https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API#unpartitioned_versus_partitioned_cookies) cookies to improve privacy (e.g., to prevent tracking), and is part of the [Storage Access API](https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API).

To check whether permission to access third-party cookies has already been granted, you can call [Permissions.query()](https://developer.mozilla.org/en-US/docs/Web/API/Permissions/query), specifying the feature name `"storage-access"`.

After an embed has activated `storage-access` permission via `requestStorageAccess()`, it should reload itself.
The browser will re-request the resource with third-party unpartitioned cookies included, and make them available to the embedded resource once it has loaded.

Third-party cookies are sent only with requests to the embedded resource's exact origin.
Other origins within the same site that wish to access their third-party cookies will need to _activate_ the granted storage-access permission.
The [storage access headers](https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API#storage_access_headers) should be used for activating a granted `storage-access` permission.
Note that the headers can activate a granted permission for any embedded resource, such as credentialed images, not just code embedded in an [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe).

It is also possible to activate a granted permission for a cross-origin, same-site endpoint by calling `requestStorageAccess()` (this time without the requirement for transient activation).
However, this only works to activate permission for embedded code.
It is also less efficient than using the headers, because the resource needs to be loaded in order to activate the permission.

> **NOTE:**
> Usage of this feature may be blocked by a [storage-access](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy%2Fstorage-access) [Permissions Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/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](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/Clickjacking) heuristics, or prompting the user for explicit permission.

## Syntax

```js-nolint
requestStorageAccess()
requestStorageAccess(types)
```

### Parameters

- `types` 
  - : 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](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/sessionStorage) should be made accessible.
    - `localStorage`
      - : A boolean specifying [StorageAccessHandle.localStorage](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/localStorage) should be made accessible.
    - `indexedDB`
      - : A boolean specifying [StorageAccessHandle.indexedDB](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/indexedDB) should be made accessible.
    - `locks`
      - : A boolean specifying [StorageAccessHandle.locks](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/locks) should be made accessible.
    - `caches`
      - : A boolean specifying [StorageAccessHandle.caches](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/caches) should be made accessible.
    - `getDirectory`
      - : A boolean specifying [StorageAccessHandle.getDirectory()](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/getDirectory) should be made accessible.
    - `estimate`
      - : A boolean specifying [StorageAccessHandle.estimate()](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/estimate) should be made accessible.
    - `createObjectURL`
      - : A boolean specifying [StorageAccessHandle.createObjectURL()](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/createObjectURL) should be made accessible.
    - `revokeObjectURL`
      - : A boolean specifying [StorageAccessHandle.revokeObjectURL()](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/revokeObjectURL) should be made accessible.
    - `BroadcastChannel`
      - : A boolean specifying [StorageAccessHandle.BroadcastChannel()](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/BroadcastChannel) should be made accessible.
    - `SharedWorker`
      - : A boolean specifying [StorageAccessHandle.SharedWorker()](https://developer.mozilla.org/en-US/docs/Web/API/StorageAccessHandle/SharedWorker) should be made accessible.

### Return value

A [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that fulfills with `undefined` if the access to third-party cookies was granted and no `types` parameter was provided, fulfills with [StorageAccessHandle](https://developer.mozilla.org/en-US/docs/Web/API/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](https://developer.mozilla.org/en-US/docs/Glossary/transient%20activation)), 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](https://developer.mozilla.org/en-US/docs/Web/API/DOMException)
  - : Thrown if:
    - The current [Document](https://developer.mozilla.org/en-US/docs/Web/API/Document) is not yet active.
    - The `types` parameter is provided and all of its properties are `false`.
- `NotAllowedError` [DOMException](https://developer.mozilla.org/en-US/docs/Web/API/DOMException)
  - : Thrown if:
    - The document's window is not a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts).
    - Usage is blocked by a [storage-access](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy%2Fstorage-access) [Permissions Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Permissions_Policy).
    - The document or the top-level document has a `null` origin.
    - The embedding [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/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

### Basic usage

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

> **NOTE:**
> See [Using the Storage Access API](https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API/Using) for a more complete example.

## Specifications

## Browser compatibility

## See also

- [Document.hasStorageAccess()](https://developer.mozilla.org/en-US/docs/Web/API/Document/hasStorageAccess), [Document.hasUnpartitionedCookieAccess()](https://developer.mozilla.org/en-US/docs/Web/API/Document/hasUnpartitionedCookieAccess), [Document.requestStorageAccessFor()](https://developer.mozilla.org/en-US/docs/Web/API/Document/requestStorageAccessFor)
- [Using the Storage Access API](https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API/Using)
- [Introducing Storage Access API](https://webkit.org/blog/8124/introducing-storage-access-api/) (WebKit blog)