## Description
Use the `chrome.cookies` API to query and modify cookies, and to be notified when they change.
## Permissions
`cookies`
## Manifest
To use the cookies API, you must declare the "cookies" permission in your
manifest, along with [host permissions](https://developer.chrome.com/docs/extensions/mv3/declare_permissions) for any hosts whose cookies you want
to access. For example:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
## Partitioning
[Partitioned cookies](https://developer.chrome.com/docs/privacy-sandbox/chips) allow a site to mark that certain cookies should be keyed against the
origin of the top level frame. This means that if site A is embedded using an iframe in site B
and site C, a partitioned cookie can have a different value in each.
`chrome.cookies` does not support partitioning, which means that all methods
read and write cookies from all partitions. The [`cookies.set()`](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#method-set) method stores cookies in
the default partition.
For details on the general impact of partitioning for extensions, see
[Storage and Cookies](https://developer.chrome.com/docs/extensions/mv3/storage-and-cookies#cookies-partitioning).
## Examples
You can find a simple example of using the cookies API in the
[examples/api/cookies](https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/cookies/cookie-clearer) directory. For other examples and for help in viewing
the source code, see [Samples](https://developer.chrome.com/docs/extensions/samples).
## Types
### Cookie
Represents information about an HTTP cookie.
#### Properties
- domain string
The domain of the cookie (e.g. "www.google.com", "example.com").
- expirationDate number optional
The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.
- hostOnly boolean
True if the cookie is a host-only cookie (i.e. a request's host must exactly match the domain of the cookie).
- httpOnly boolean
True if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts).
- name string
The name of the cookie.
- partitionKey [CookiePartitionKey](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-CookiePartitionKey) optional
Chrome 119+
The partition key for reading or modifying cookies with the Partitioned attribute.
- path string
The path of the cookie.
- sameSite [SameSiteStatus](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-SameSiteStatus)
Chrome 51+
The cookie's same-site status (i.e. whether the cookie is sent with cross-site requests).
- secure boolean
True if the cookie is marked as Secure (i.e. its scope is limited to secure channels, typically HTTPS).
- session boolean
True if the cookie is a session cookie, as opposed to a persistent cookie with an expiration date.
- storeId string
The ID of the cookie store containing this cookie, as provided in getAllCookieStores().
- value string
The value of the cookie.
### CookieDetails
Chrome 88+
Details to identify the cookie.
#### Properties
- name string
The name of the cookie to access.
- partitionKey [CookiePartitionKey](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-CookiePartitionKey) optional
Chrome 119+
The partition key for reading or modifying cookies with the Partitioned attribute.
- storeId string optional
The ID of the cookie store in which to look for the cookie. By default, the current execution context's cookie store will be used.
- url string
The URL with which the cookie to access is associated. This argument may be a full URL, in which case any data following the URL path (e.g. the query string) is simply ignored. If host permissions for this URL are not specified in the manifest file, the API call will fail.
### CookiePartitionKey
Chrome 119+
Represents a partitioned cookie's partition key.
#### Properties
- hasCrossSiteAncestor boolean optional
Chrome 130+
Indicates if the cookie was set in a cross-cross site context. This prevents a top-level site embedded in a cross-site context from accessing cookies set by the top-level site in a same-site context.
- topLevelSite string optional
The top-level site the partitioned cookie is available in.
### CookieStore
Represents a cookie store in the browser. An incognito mode window, for instance, uses a separate cookie store from a non-incognito window.
#### Properties
- id string
The unique identifier for the cookie store.
- tabIds number\[\]
Identifiers of all the browser tabs that share this cookie store.
### FrameDetails
Chrome 132+
Details to identify the frame.
#### Properties
- documentId string optional
The unique identifier for the document. If the frameId and/or tabId are provided they will be validated to match the document found by provided document ID.
- frameId number optional
The unique identifier for the frame within the tab.
- tabId number optional
The unique identifier for the tab containing the frame.
### OnChangedCause
Chrome 44+
The underlying reason behind the cookie's change. If a cookie was inserted, or removed via an explicit call to "chrome.cookies.remove", "cause" will be "explicit". If a cookie was automatically removed due to expiry, "cause" will be "expired". If a cookie was removed due to being overwritten with an already-expired expiration date, "cause" will be set to "expired_overwrite". If a cookie was automatically removed due to garbage collection, "cause" will be "evicted". If a cookie was automatically removed due to a "set" call that overwrote it, "cause" will be "overwrite". Plan your response accordingly.
#### Enum
"evicted"
"expired"
"explicit"
"expired_overwrite"
"overwrite"
### SameSiteStatus
Chrome 51+
A cookie's 'SameSite' state (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' corresponds to a cookie set with 'SameSite=None', 'lax' to 'SameSite=Lax', and 'strict' to 'SameSite=Strict'. 'unspecified' corresponds to a cookie set without the SameSite attribute.
#### Enum
"no_restriction"
"lax"
"strict"
"unspecified"
## Methods
### get()
Promise
```typescript
chrome.cookies.get(
details: CookieDetails,
callback?: function,
): Promise
```
Retrieves information about a single cookie. If more than one cookie of the same name exists for the given URL, the one with the longest path will be returned. For cookies with the same path length, the cookie with the earliest creation time will be returned.
#### Parameters
- details [CookieDetails](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-CookieDetails)
- callback function optional
The `callback` parameter looks like:
```typescript
(cookie?: Cookie) => void
```
- cookie [Cookie](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-Cookie) optional
Contains details about the cookie. This parameter is null if no such cookie was found.
#### Returns
- Promise\<[Cookie](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-Cookie) \| undefined\>
Chrome 88+
Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
### getAll()
Promise
```typescript
chrome.cookies.getAll(
details: object,
callback?: function,
): Promise
```
Retrieves all cookies from a single cookie store that match the given information. The cookies returned will be sorted, with those with the longest path first. If multiple cookies have the same path length, those with the earliest creation time will be first. This method only retrieves cookies for domains that the extension has host permissions to.
#### Parameters
- details object
Information to filter the cookies being retrieved.
- domain string optional
Restricts the retrieved cookies to those whose domains match or are subdomains of this one.
- name string optional
Filters the cookies by name.
- partitionKey [CookiePartitionKey](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-CookiePartitionKey) optional
Chrome 119+
The partition key for reading or modifying cookies with the Partitioned attribute.
- path string optional
Restricts the retrieved cookies to those whose path exactly matches this string.
- secure boolean optional
Filters the cookies by their Secure property.
- session boolean optional
Filters out session vs. persistent cookies.
- storeId string optional
The cookie store to retrieve cookies from. If omitted, the current execution context's cookie store will be used.
- url string optional
Restricts the retrieved cookies to those that would match the given URL.
- callback function optional
The `callback` parameter looks like:
```typescript
(cookies: Cookie[]) => void
```
- cookies [Cookie](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-Cookie)\[\]
All the existing, unexpired cookies that match the given cookie info.
#### Returns
- Promise\<[Cookie](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-Cookie)\[\]\>
Chrome 88+
Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
### getAllCookieStores()
Promise
```typescript
chrome.cookies.getAllCookieStores(
callback?: function,
): Promise
```
Lists all existing cookie stores.
#### Parameters
- callback function optional
The `callback` parameter looks like:
```typescript
(cookieStores: CookieStore[]) => void
```
- cookieStores [CookieStore](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-CookieStore)\[\]
All the existing cookie stores.
#### Returns
- Promise\<[CookieStore](https://developer.chrome.com/docs/extensions/mv2/reference/cookies#type-CookieStore)\[\]\>
Chrome 88+
Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
### getPartitionKey()
Promise Chrome 132+
```typescript
chrome.cookies.getPartitionKey(
details: FrameDetails,
callback?: function,
): Promise