W3cubDocs

/Web Extensions

cookies

Enables extensions to get and set cookies, and be notified when they change.

To use this API, you need to include the "cookies" API permission in your manifest.json file, as well as host permissions for the sites whose cookies you need to access. See cookie Permissions.

Permissions

In order to use this API, an add-on must specify the "cookies" API permission in its manifest, along with host permissions for any sites for which it wishes to access cookies. The add-on may read or write any cookies which could be read or written by a URL matching the host permissions. For example:

http://*.example.com/

An add-on with this host permission may:

  • Read a non-secure cookie for www.example.com, with any path.
  • Write a secure or non-secure cookie for www.example.com, with any path.

It may not:

  • Read a secure cookie for www.example.com.
http://www.example.com/

An add-on with this host permission may:

  • Read a non-secure cookie for www.example.com, with any path.
  • Read a non-secure cookie for .example.com, with any path.
  • Write a secure or non-secure cookie for www.example.com with any path.
  • Write a secure or non-secure cookie for .example.com with any path.

It may not:

  • Read or write a cookie for foo.example.com.
  • Read or write a cookie for foo.www.example.com.
*://*.example.com/

An add-on with this host permission may:

  • Read or write a secure or non-secure cookie for www.example.com with any path.

First-party isolation

Third-party cookies are cookies that are set by a website other than the one you are currently on. For example:

  1. You visit bbc.com. It contains an ad from tracker.com that sets a cookie associated with the "tracker.com" domain.
  2. You visit cnn.com. It also contains an ad from tracker.com that sets a cookie associated with the "tracker.com" domain.
  3. Eventually both cookies can be sent to tracker.com. who can then figure out that the same user visited both sites.

When first-party isolation is on, cookies are further qualified by the domain of the original page the user visited (essentially, the domain shown to the user in the URL bar, also known as the "first party domain"). This means it's not possible for a tracker to correlate its cookie from bbc.com with its cookie from cnn.com, so the tracker can't track a single user across both sites.

First-party isolation can be enabled directly by the user by adjusting the browser's configuration, and can be set by extensions using the firstPartyIsolate setting in the privacy API. Note that first-party isolation is enabled by default in Tor Browser.

In the cookies API, the first party domain is represented using the firstPartyDomain attribute. All cookies set while first-party isolation is on will have this attribute set to the domain of the original page. In the example above, this would be "bbc.com" for one cookie and "cnn.com" for the other. All cookies set by websites while first-party isolation is off will have this property set to an empty string.

The cookies.get(), cookies.getAll(), cookies.set() and cookies.remove() APIs all accept a firstPartyDomain option.
When first-party isolation is on, you must provide this option or the API call will fail and return a rejected promise. For get(), set(), and remove() you must pass a string value. For getAll(), you may also pass null here, and this will get all cookies, whether or not they have a non-empty value for firstPartyDomain.
When first-party isolation is off, the firstPartyDomain parameter is optional and defaults to an empty string. A non-empty string can be used to retrieve or modify first-party isolation cookies. Likewise, passing null as firstPartyDomain to getAll() will return all cookies.

Types

cookies.Cookie
Represents information about an HTTP cookie.
cookies.CookieStore
Represents a cookie store in the browser.
cookies.OnChangedCause
Represents the reason a cookie changed.
cookies.SameSiteStatus
Represents the same-site status of the cookie.

Methods

cookies.get()
Retrieves information about a single cookie.
cookies.getAll()
Retrieves all cookies that match a given set of filters.
cookies.set()
Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist.
cookies.remove()
Deletes a cookie by name.
cookies.getAllCookieStores()
Lists all existing cookie stores.

Event handlers

cookies.onChanged
Fired when a cookie is set or removed.

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
Cookie
Yes
14
45
?
Yes
14
?
?
48
?
?
?
CookieStore
Yes
14
45
?
Yes
14
?
?
48
?
?
?
OnChangedCause
Yes
79
45
?
Yes
No
?
?
48
?
?
?
get
Yes
14
45
Provides access to cookies from private browsing mode and container tabs since version 52.
?
Yes
14
HTTPOnly cookies are not retrieved.
?
?
48
?
?
?
getAll
Yes
14
If no URL is provided, cookies are retrieved only for URLs in currently opened tabs. In Chrome, this gets all cookies on a user's machine.
45
Before version 52, the 'tabIds' list was empty and only cookies from the default cookie store were returned. From version 52 onwards, this has been fixed and the result includes cookies from private browsing mode and container tabs.
?
Yes
14
["Only the cookies in the default cookie store are retrieved.", "HTTPOnly cookies are not retrieved."]
?
?
48
?
?
?
getAllCookieStores
Yes
14
Always returns the same default cookie store with ID 0. All cookies belong to this store.
45
Before version 52, only the default cookie store was visible. From version 52 onwards, the cookie stores for private browsing mode and container tabs are also readable.
?
Yes
14
Always returns the same default cookie store with ID 0.
?
?
48
?
?
?
onChanged
Yes
79
45
?
Yes
No
?
?
48
?
?
?
remove
Yes
14
45
Before version 56, this function did not remove cookies from private browsing mode. From version 56 onwards this is fixed.
?
Yes
14
?
?
48
Before version 56, this function did not remove cookies from private browsing mode. From version 56 onwards this is fixed.
?
?
?
sameSiteStatus
Yes
79
63
?
No
14
Only supports explicit.
?
?
63
?
?
?
set
Yes
14
45
Before version 56, this function did not modify cookies in private browsing mode. From version 56 onwards this is fixed.
?
Yes
14
?
?
48
Before version 56, this function did not modify cookies in private browsing mode. From version 56 onwards this is fixed.
?
?
?

Example extensions

Note: This API is based on Chromium's chrome.cookies API. This documentation is derived from cookies.json in the Chromium code.

© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies