What Is the Storage Access API?
The Storage Access API is a JavaScript API that enables content embedded in iframes to request access to storage mechanisms--specifically third-party cookies and unpartitioned state--that would typically be blocked when loaded in a cross-site context.
Modern browsers block access to third-party cookies by default to protect user privacy. While this prevents cross-site tracking, it also breaks legitimate use cases like embedded login systems, single sign-on providers, and cross-domain services.
The Storage Access API bridges this gap by providing a mechanism for embedded content to:
- Check whether it currently has storage access
- Request access to storage when needed
- Have that access granted in a privacy-respecting manner
For developers working on modern web applications, understanding how browser storage APIs interact is essential. Our /services/web-development/ team regularly implements these patterns for embedded widgets and cross-site integrations.
Core API Methods
Checking Storage Access: hasStorageAccess()
The hasStorageAccess() method returns a Promise that resolves to a boolean indicating whether the current document has storage access. This method allows embedded content to check its access status before attempting to read or write cookies. Always check storage access status before attempting operations because browsers may return an empty cookie jar when third-party access is blocked, and the access status may have changed since the last page visit.
async function checkStorageAccess() {
if (!document.hasStorageAccess) {
// API not supported - handle gracefully
console.log('Storage Access API not supported');
return false;
}
const hasAccess = await document.hasStorageAccess();
if (hasAccess) {
console.log('Storage access already granted');
return true;
} else {
console.log('No storage access - need to request');
return false;
}
}
Requesting Storage Access: requestStorageAccess()
The requestStorageAccess() method returns a Promise that resolves when access is granted or rejects when denied. A critical requirement is that this method must be called within a user activation handler such as a click event. This prevents silent access requests and ensures users maintain control over when their storage is shared with embedded content.
async function requestStorageAccess() {
if (!document.requestStorageAccess) {
console.log('Storage Access API not supported');
return false;
}
try {
await document.requestStorageAccess();
console.log('Storage access granted');
return true;
} catch (error) {
console.log('Storage access denied:', error);
return false;
}
}
User Activation Requirement
User activations are transient states triggered by user interactions like clicks, taps, or key presses. This requirement prevents websites from silently requesting storage access without user awareness. Requests triggered outside of user activation contexts will be rejected by the browser.
1class StorageAccessManager {2 async initialize() {3 if (!this.checkAPISupport()) {4 return false;5 }6 this.hasAccess = await document.hasStorageAccess();7 if (!this.hasAccess) {8 await this.checkPermissionState();9 }10 return this.hasAccess;11 }12 13 checkAPISupport() {14 return !!(document.hasStorageAccess && document.requestStorageAccess);15 }16 17 async checkPermissionState() {18 try {19 const permission = await navigator.permissions.query({20 name: 'storage-access'21 });22 if (permission.state === 'granted') {23 this.hasAccess = await document.requestStorageAccess();24 }25 } catch (error) {26 console.warn('Permission query failed:', error);27 }28 }29 30 async requestAccess() {31 try {32 await document.requestStorageAccess();33 this.hasAccess = true;34 return { success: true };35 } catch (error) {36 return { success: false, reason: error.message };37 }38 }39}Browser Compatibility and Variations
Browser Support
| Browser | Version | Notes |
|---|---|---|
| Chrome | 119+ | Full support with RWS and FedCM integration |
| Edge | 85+ | Based on Chromium |
| Firefox | 65+ | Threshold-based prompting |
| Safari | 11.1+ | Stricter user activation requirements |
Chrome-Specific Behavior
Chrome implements the Storage Access API with several auto-grant scenarios:
- Related Website Sets: Sites in the same RWS receive automatic access
- Recent Interaction: Access auto-granted if user interacted in past 30 days
- FedCM Integration: Login via FedCM enables auto-grant
Chrome also has a 30-day validity period for storage access grants. When access expires, the browser will prompt the user again.
Firefox-Specific Behavior
Firefox uses a threshold-based prompting system:
- For the first 5 attempts on known sites (sites the user has visited in a first-party context), Firefox automatically grants access without prompting
- After the threshold is reached, Firefox will prompt the user
- Firefox respects the user's global cookie settings
Safari-Specific Behavior
Safari has stricter requirements:
- Always requires user activation before requestStorageAccess()
- Per-page access model where access granted to one embed applies to all embeds from the same site
- Affected by Intelligent Tracking Prevention (ITP)
Privacy-Preserving
Requires user consent through explicit interactions, giving users control over their data
Cross-Browser Standard
Supported by all major browsers with standardized behavior
Permission-Based
Uses a permission system that can be queried and managed
Integration Ready
Works with FedCM, CHIPS, and Related Website Sets
Related Technologies
CHIPS (Cookies Having Independent Partitioned State)
CHIPS allows developers to opt cookies into partitioned storage. Each top-level site gets its own separate cookie jar. Use CHIPS when the embedded service only needs data for the current site and cross-site data sharing is not required. CHIPS is simpler than Storage Access API because it doesn't require user permission prompts, but it doesn't provide access to unpartitioned state.
FedCM (Federated Credential Management)
FedCM provides a privacy-preserving approach for federated identity services. When users log in via FedCM, the identity provider can automatically get storage access without additional prompts. This integration streamlines the login experience while maintaining privacy. FedCM can serve as a trust signal for Storage Access API requests, making access grants more likely.
Related Website Sets (RWS)
Related Website Sets allow organizations to declare relationships between their sites. Sites within the same set can receive automatic storage access grants without user prompts and are treated as related for privacy purposes. They still need to call requestStorageAccess() to activate the permission. RWS is particularly useful for organizations with multiple domains that need to share user data legitimately.
To understand how Storage Access API fits into the broader browser storage landscape, explore our guides on /resources/docs/llms-and-agents/local-storage-and-how-to-use-it/ and /resources/docs/llms-and-agents/a-primer-on-the-different-types-of-browser-storage/ for comprehensive coverage of browser storage options.
Best Practices and Common Questions
Embedded Login Widgets
SSO providers embedded in third-party sites need access to session cookies to maintain user authentication across properties.
Comment Systems
Comment widgets that support authenticated users need access to session cookies to display personalized comments and user info.
Social Media Integration
Like buttons, share widgets, and embeds that personalize features based on user accounts require storage access.
Cross-Site Preferences
Services that remember user settings across multiple owned domains can use Storage Access API for consistent experiences.
Embedded Video Players
Video embeds that remember playback position, volume, and quality preferences across sites.
Payment Systems
Embedded checkout flows that need to access payment preferences or saved payment methods.
Conclusion
The Storage Access API provides a standardized mechanism for embedded cross-site content to access storage while respecting user privacy. By requiring user activation and providing transparent permission prompts, it enables legitimate use cases like embedded login systems and SSO while preventing unauthorized tracking.
For developers building LLM-powered applications that may involve embedded cross-site content, understanding and properly implementing the Storage Access API is essential for creating seamless user experiences that respect privacy boundaries. The key is to use the API only for its intended purposes--legitimate cross-site services that users intentionally interact with--and to always provide graceful fallbacks for users who choose not to grant access.
Key takeaways:
- Always check hasStorageAccess() before requesting
- Trigger requests from clear user interactions
- Handle denials gracefully with fallbacks
- Test across browsers due to behavioral differences
- Consider alternatives like CHIPS when appropriate
As browser privacy features continue to evolve, the Storage Access API represents a thoughtful balance between functional requirements and user privacy protection, making it a critical tool for modern web development. Our /services/ai-automation/ team specializes in building sophisticated AI applications that leverage modern browser APIs while respecting user privacy.
Sources
- MDN Web Docs - Storage Access API - Comprehensive official documentation covering API concepts, methods, and security considerations
- MDN Web Docs - Using the Storage Access API - Practical implementation guide with code examples
- Privacy Sandbox - Storage Access API - Google's official documentation on implementation status and FedCM integration
- Privacy CG Storage Access API Specification - Official W3C specification defining technical requirements