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
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 theallow-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("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