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

Example extensions

• cookie-bg-picker
• list-cookies