The Storage Access API is a JavaScript tool that allows embedded content, such as iframes, to request access to third-party cookies and unpartitioned storage. It bridges the gap between strict browser privacy policies and the functional needs of cross-site services. Marketers and developers use this to maintain user sessions for commenting systems, social widgets, and single sign-on (SSO) flows that would otherwise be blocked by modern browsers.
What is the Storage Access API?
The Storage Access API provides a standardized way for cross-site content loaded in a third-party context to gain access to cookies it would usually only see in a first-party context. Browsers now use storage partitioning or block third-party cookies by default to protect user privacy and prevent cross-site tracking.
This API is only necessary for accessing unpartitioned data. Unpartitioned data is the traditional cookie storage where all cookies for a domain are kept in one place. In contrast, partitioned cookies (like CHIPS) isolate storage to a specific top-level site, preventing users from being tracked across the web but also preventing them from staying logged in across different company-owned domains.
Why Storage Access API matters
- Maintains Authentication: Allows users to stay logged in across related domains, such as a utility site (
sso-example.com) embedded within several product sites. - Powers Engagement Widgets: Enables third-party commenting systems and social "Like" buttons to recognize a user's logged-in status.
- Enhances Personalization: Permits video players or documents to remember user preferences, such as closed caption settings or ad-free status.
- Simplifies User Experience: Replaces the need to ask users to manually disable browser security settings with a specific, frame-by-frame permission request.
- Reduces Security Risks: Limits data access to specific pairs of sites rather than opening the browser to all third-party tracking.
How the Storage Access API works
The API operates through a specific sequence of checks and requests designed to ensure the user actually wants the interaction to occur.
- Check Status: The embedded content calls
document.hasStorageAccess()to see if it already has permission to read unpartitioned cookies. - User Gesture: If access is missing, the site must wait for a user interaction, such as a click or tap. This is known as [Transient Activation] (MDN Web Docs).
- Request Access: Within the click handler, the script calls
document.requestStorageAccess(). - Browser Decision: The browser checks if the user has visited the embedded site as a first-party recently. [Firefox defines "recently" as within the last 30 days] (MDN Web Docs).
- Activation: Once granted, the script can access cookies. The browser may require a page reload to include those cookies in the next network request.
Storage Access Headers
Available starting in [Chrome 133] (Privacy Sandbox), these HTTP headers allow a faster workflow. The server can send an Activate-Storage-Access: retry header to tell the browser to activate an existing permission and retry the request with cookies immediately, avoiding a full JavaScript-driven reload.
Browser-specific variations
While the API is widely supported, browsers implement different gatekeeping logic.
| Feature | Chrome | Firefox | Safari |
|---|---|---|---|
| Cookie Requirements | Requires SameSite=None and Secure. |
Defaults to SameSite=None. |
Defaults to SameSite=None. |
| Prompt Logic | Skips prompts for [Related Website Sets] (MDN Web Docs). | Skips prompt for first 5 attempts on known sites. | Usually shows a prompt for all new embeds. |
| Expiration | Grant lasts [30 days of browser usage] (MDN Web Docs). | Grant lasts 30 calendar days. | Grant lasts 30 days of browser usage. |
| Permission Scope | Strictly follows same-origin policy. | Per-site access grants. | Access is per-site rather than per-origin. |
Best practices
- Always use HTTPS: The API only functions in secure contexts.
- Prompt on Interaction: Do not trigger request calls on page load. Call
requestStorageAccess()only when a user clicks a "Login" or "Interact" button to avoid automatic rejection. - Check for Support: Use feature detection before calling methods. For example, [Chrome 125 introduced the name
hasUnpartitionedCookieAccess] (Privacy Sandbox) as an alias for broader compatibility. - Coordinate with RWS: If you manage multiple domains (e.g., .com and .co.uk), use Chrome’s Related Website Sets to allow the browser to skip user prompts entirely.
- Configure Iframes Properly: If using sandboxed iframes, you must include the
allow-storage-access-by-user-activationtoken.
Common mistakes
Mistake: Calling the API for a site the user has never visited directly. Fix: Ensure the user has visited the embedded domain as a first-party site (in its own tab) before expecting the API to grant access in an iframe.
Mistake: Omitting SameSite=None or Secure flags on cookies in Chrome.
Fix: Explicitly set these attributes, as Chrome defaults to SameSite=Lax, which prevents cross-site sharing even with API approval.
Mistake: Assuming a grant in one tab applies to all tabs.
Fix: Storage access is typically granted per-frame or per-context; other tabs or iframes will need to call requestStorageAccess() to activate the existing permission.
Mistake: Forgetting to handle the "Rejected" state.
Fix: Use a .catch() block to provide a fallback experience, such as a link that opens the third-party site in a new window.
Storage Access API vs. CHIPS
| Feature | Storage Access API | CHIPS (Partitioned Cookies) |
|---|---|---|
| Goal | Access the main, shared cookie jar. | Create a new, isolated cookie jar. |
| User Interaction | Required (click/prompt). | Not required. |
| Sharing | Shares data across different top-level sites. | Data is unique to the specific top-level site. |
| Best Use Case | Cross-domain SSO or shared user profiles. | Third-party chat widgets or site-specific bits. |
FAQ
Does the Storage Access API work for all types of storage?
Yes, it has been extended beyond cookies. By passing a types parameter, you can [request access to unpartitioned LocalStorage, IndexedDB, and other mechanisms] (Privacy Sandbox).
Why am I seeing a "NotAllowedError"?
This usually happens if the API call was not triggered by a user gesture like a click, or if the user has not visited the domain in a first-party context recently.
How do I use this for non-iframe resources like images?
Chrome supports document.requestStorageAccessFor(), which allows a top-level site to request access on behalf of cross-site resources like images or scripts, provided they are in the same Related Website Set.
Is there a performance impact when using this API?
The standard JavaScript workflow requires the iframe to load once without cookies, call the API, and then potentially reload. Using [Storage Access Headers] (Privacy Sandbox) in Chrome 133 or later can mitigate this by handling the retry at the network level.
Will Safari users always see a prompt?
Safari is generally more restrictive and often requires a user gesture for every new session, even if permission was granted in a previous visit.
