---
title: Storage Access API
slug: Web/API/Storage_Access_API
tags:
  - API
  - Reference
  - Storage
  - Storage Access API
translation_of: Web/API/Storage_Access_API
---
<div>{{DefaultAPISidebar("Storage Access API")}}{{seecompattable}}</div>

<p><span class="seoSummary">The Storage Access API provides a way for embedded, cross-origin content to gain unrestricted access to storage that it would normally only have access to in a first-party context (we refer to this as an origin’s <em>first-party</em> storage).</span> The API provides methods that allow embedded resources to check whether they currently have access to their first-party storage, and to request access to their first-party storage from the user agent.</p>

<h2 id="Концепции_и_использование">Концепции и использование</h2>

<p>Most browsers implement a number of storage access policies that restrict access to cookies and site data for embedded, cross-origin resources. These restrictions range from giving embedded resources under each top-level origin a unique storage space to outright blocking of storage access when resources are loaded in a third-party context.</p>

<p>The semantics around third-party cookie blocking policies in particular differ from browser to browser, but the core functionality is similar: cross-origin resources embedded in a third-party context are not given access to the same cookies and site storage that they would have access to when loaded in a first-party context.</p>

<p>These cookie blocking policies are known to break embedded cross-origin content that requires access to its first-party storage. As an example, federated logins often require access to authentication cookies stored in first-party storage, and will require the user to sign in on each site separately (or completely break) if those cookies are not available. In the case of breakage, site owners have often encouraged users to add their site as an exception or to disable the policy entirely. As a consequence, users who wish to continue to interact with embedded content are forced to greatly relax their blocking policy for resources loaded from all embedded origins and possibly across all websites.</p>

<p>The Storage Access API is intended to solve this problem; embedded cross-origin content can request unrestricted access to its first-party storage on a site-by-site basis via the {{domxref("Document.requestStorageAccess()")}} method, and check whether it already has access via the {{domxref("Document.hasStorageAccess()")}} method.</p>

<p>In addition, sandboxed {{htmlelement("iframe")}}s cannot be granted storage access by default for security reasons. The API therefore also adds the <code>allow-storage-access-by-user-activation</code> <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-sandbox">sandbox token</a>. The embedding website needs to add this to allow storage access requests to be successful, along with <code>allow-scripts</code> and <code>allow-same-origin</code> to allow it to call the API, and execute in an origin that can have cookies:</p>

<pre class="brush: html notranslate">&lt;iframe sandbox="allow-storage-access-by-user-activation
                 allow-scripts
                 allow-same-origin"&gt;
  ...
&lt;/iframe&gt;</pre>

<p>The API is designed to limit the potential storage exceptions to origins for which the user has shown an intent to interact. This is enforced through the following constraints:</p>

<ul>
 <li>Access requests are automatically denied unless the embedded content is currently processing a user gesture such as a tap or click. This also prevents embedded content on the page from spamming the browser or user with excessive access requests.</li>
 <li>Origins that have never been interacted with as a first party do not have a notion of first-party storage. From the user’s perspective, they only have a third-party relationship with that origin. Access requests are automatically denied if the browser detects that the user hasn’t interacted with the embedded content in a first-party context recently (in Firefox, "recently" is "within 30 days").</li>
</ul>

<p>The browser may decide to involve the user in the decision of whether to grant an incoming storage access request. Specifics regarding the lifetime of a storage grant and the circumstances under which the browser may decide to inform the user are currently being worked through and will be announced once ready.</p>

<h2 id="Подсказки_для_пользователя">Подсказки для пользователя</h2>

<p>When <code>requestStorageAccess()</code> is called by an embedded, cross-origin document, the user agent may choose to involve the user in the decision of whether to grant storage access to the requesting origin. Prompting heuristics currently vary across the two implementers of the Storage Access API — Safari shows prompts for all embedded tracking content that has not previously received storage access, while Firefox only prompts users after a tracking origin has requested storage access on more than a threshold number of sites. See {{domxref("Document.requestStorageAccess()")}} for more details.</p>

<h2 id="Отличия_реализации_в_Safari">Отличия реализации в Safari</h2>

<p>Although the API surface is the same, websites using the Storage Access API should expect differences in the level and extent of storage access they receive between Firefox and Safari. This is caused by differences in the storage access policies implemented in the two browsers. Design properties unique to Firefox are summarized here:</p>

<ul>
 <li>If the embedded origin <code>tracker.example</code> has already obtained first-party storage access on the top-level origin <code>foo.example</code>, and the user visits a page from <code>foo.example</code> embedding a page from <code>tracker.example</code> again in less than 30 days, the embedded origin will have storage access immediately when loading.</li>
 <li>If a page from top-level origin <code>foo.example</code> embeds more than one {{htmlelement("iframe")}} from <code>tracker.example</code>, and one of those <code>&lt;iframe&gt;</code>s uses the Storage Access API in order to obtain storage access successfully, all other iframes from <code>tracker.example</code> on <code>foo.example</code> top-level origins will immediately gain storage access as well, without needing to call <code>requestStorageAccess()</code> separately.</li>
 <li>If an embedded page from <code>tracker.example</code> has previously successfully obtained storage access on top-level origin <code>foo.example</code>, all embedded subresources from <code>tracker.example</code> on <code>foo.example</code> (e.g. scripts, images, stylesheets, etc.) will load with access to their first-party storage, which means they may send Cookie headers and honor incoming {{httpheader("Set-Cookie")}} headers.</li>
 <li>In Firefox, when the promise returned from <code>requestStorageAccess()</code> is resolved, the embedded page will gain access to its entire first-party storage, not just cookies.  This includes access to APIs such as <a href="/en-US/docs/Web/API/Web_Storage_API">Web Storage</a>, <a href="/en-US/docs/Web/API/IndexedDB_API">IndexedDB</a>, <a href="/en-US/docs/Web/API/Cache">DOM Cache</a>, and so on.</li>
 <li>In Firefox, the storage access grants are phased out after 30 calendar days passing, whereas in Safari the storage access grants are phased out after 30 days of browser usage passed without user interaction. This is currently a limitation of the Firefox implementation, which we may address in a future version.  In Safari, successful use of the storage access API resets this counter.</li>
</ul>

<p>Документация новой политики доступа к хранилищу Firefox по блокировки отслеживающих кук <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Privacy/Storage_access_policy#Storage_access_grants">детально описана</a> в разделе предоставления доступа к хранилищу.</p>

<h2 id="Методы_Storage_Access_API">Методы Storage Access API</h2>

<p>API методы реализованы в интерфейсе {{domxref("Document")}}:</p>

<dl>
 <dt>{{domxref("Document.hasStorageAccess()")}}</dt>
 <dd>Returns a {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to its first-party storage.</dd>
 <dt>{{domxref("Document.requestStorageAccess()")}}</dt>
 <dd>Returns a {{jsxref("Promise")}} that resolves if the access to first-party storage was granted, and rejects if access was denied.</dd>
</dl>

<div class="note">
<p><strong>Note</strong>: User interaction propagates to the Promise returned by both of these methods, allowing the callers to take actions that require user interaction without requiring a second click from the user. For example, a caller could open a pop-up window from the resolved Promise without triggering Firefox’s pop-up blocker.</p>
</div>

<h2 id="Расширение_&lt;iframe>_sandbox">Расширение &lt;iframe&gt; sandbox</h2>

<p>{{htmlelement("iframe")}} <code>sandbox</code> появился новый признак, <code>allow-storage-access-by-user-activation</code>, который позволяет изолированному <code>&lt;iframe&gt;</code> использовать Storage Access API для запроса доступа к хранилищу.</p>

<h2 id="Спецификации">Спецификации</h2>

<p>API на стадии обсуждения — стандартизация не начата. Сейчас вы можете ознакомиться с подробной спецификацией API в блоге Apple <a href="https://webkit.org/blog/8124/introducing-storage-access-api/">Introducing Storage Access API</a> и <a href="https://github.com/whatwg/html/issues/3338">WHATWG HTML issue 3338 — Proposal: Storage Access API</a>.</p>

<h2 id="Поддержка_браузерами">Поддержка браузерами</h2>



<p>{{Compat("api.Document.hasStorageAccess")}}</p>

<p>{{Compat("api.Document.requestStorageAccess")}}</p>

<h2 id="Смотрите_также">Смотрите также</h2>

<p><a href="/en-US/docs/Web/API/Storage_Access_API/Using">Использование Storage Access API</a></p>