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

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
CookieChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
CookieStoreChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
OnChangedCauseChrome Full support YesEdge No support NoFirefox Full support 45Opera Full support YesFirefox Android Full support 48
getChrome Full support YesEdge Full support 14Firefox Full support 45
Notes
Full support 45
Notes
Notes Provides access to cookies from private browsing mode and container tabs since version 52.
Opera Full support YesFirefox Android Full support 48
getAllChrome Full support YesEdge Full support 14
Notes
Full support 14
Notes
Notes 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.
Firefox Full support 45
Notes
Full support 45
Notes
Notes 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.
Opera Full support YesFirefox Android Full support 48
getAllCookieStoresChrome Full support YesEdge Full support 14
Notes
Full support 14
Notes
Notes Always returns the same default cookie store with ID 0. All cookies belong to this store.
Firefox Full support 45
Notes
Full support 45
Notes
Notes 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.
Opera Full support YesFirefox Android Full support 48
onChangedChrome Full support YesEdge No support NoFirefox Full support 45Opera Full support YesFirefox Android Full support 48
removeChrome Full support YesEdge Full support 14Firefox Full support 45
Notes
Full support 45
Notes
Notes Before version 56, this function did not remove cookies from private browsing mode. From version 56 onwards this is fixed.
Opera Full support YesFirefox Android Full support 48
Notes
Full support 48
Notes
Notes Before version 56, this function did not remove cookies from private browsing mode. From version 56 onwards this is fixed.
setChrome Full support YesEdge Full support 14Firefox Full support 45
Notes
Full support 45
Notes
Notes Before version 56, this function did not modify cookies in private browsing mode. From version 56 onwards this is fixed.
Opera Full support YesFirefox Android Full support 48
Notes
Full support 48
Notes
Notes Before version 56, this function did not modify cookies in private browsing mode. From version 56 onwards this is fixed.

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

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: irenesmith,