MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/MDN-survey

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 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 calls will fail.

For get(), set(), and remove() you must pass a non-null value for firstPartyDomain. 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.

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.

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

ChromeEdgeFirefoxFirefox for AndroidOpera
Cookie Yes Yes4548 Yes
CookieStore Yes Yes4548 Yes
OnChangedCause Yes No4548 Yes
get Yes Yes45 *48 Yes
getAll Yes Yes *45 *48 Yes
getAllCookieStores Yes Yes *45 *48 Yes
onChanged Yes No4548 Yes
remove Yes Yes45 *48 * Yes
set Yes Yes45 *48 * Yes

Example extensions

Acknowledgements

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

Document Tags and Contributors

 Last updated by: wbamberg,