Chrome Cookies API Complete Guide for Extensions

January 17, 2025 · 21 min read · Chrome Extensions, API Guide

Chrome Cookies API Complete Guide for Extensions

The Chrome Cookies API is an essential tool for extension developers who need to read, modify, and manage browser cookies. Whether you’re building a cookie manager, implementing session handling, creating login managers, or developing privacy-focused extensions, understanding the Chrome Cookies API is fundamental to creating powerful and functional Chrome extensions.

This comprehensive guide covers everything you need to know about the Chrome Cookies API, from basic cookie retrieval to advanced manipulation techniques. We’ll explore real-world use cases, code examples, best practices, and common pitfalls to help you build robust cookie management features in your extensions.

Understanding the Chrome Cookies API

The Chrome Cookies API, accessible via chrome.cookies, provides a comprehensive set of methods for managing browser cookies. This API allows extensions to interact with cookies stored by the browser, enabling a wide range of functionality from simple cookie reading to complex cookie synchronization and management.

What Are Cookies and Why They Matter

Cookies are small pieces of data stored in the browser that websites use to remember user information, maintain sessions, track preferences, and provide personalized experiences. In the context of Chrome extensions, cookies become even more powerful as they allow your extension to interact with website sessions, manage authentication states, and implement sophisticated data handling features.

The Chrome Cookies API enables your extension to:

Retrieve cookies from any domain
Set new cookies with custom properties
Update existing cookie values
Delete specific cookies or clear all cookies
Monitor cookie changes in real-time
Filter and query cookies based on various criteria

Chrome’s cookie system is built on the Chromium browser engine, which maintains cookies in a secure database. The Chrome Cookies API provides a bridge between your extension and this internal cookie storage, offering a standardized way to interact with cookie data across different websites and domains.

Required Permissions and Manifest Configuration

Before you can use the Chrome Cookies API in your extension, you need to configure your manifest.json file properly. The permission requirements depend on which operations you need to perform.

Basic Permission Setup

For most cookie operations, you’ll need to declare the "cookies" permission in your manifest:

{
  "name": "Cookie Manager Pro",
  "version": "1.0",
  "description": "A powerful cookie management extension",
  "permissions": [
    "cookies"
  ],
  "host_permissions": [
    "*://*.example.com/*"
  ],
  "manifest_version": 3
}

Understanding Host Permissions

The Chrome Cookies API has a unique permission model that requires host permissions for cookie access. This is a security feature that prevents extensions from accessing cookies without explicit authorization. You need to specify which domains your extension can access cookies from using the host_permissions field.

For accessing cookies from all websites, you can use:

"host_permissions": [
  "<all_urls>"
]

For specific domains:

"host_permissions": [
  "*://*.google.com/*",
  "*://*.facebook.com/*",
  "https://example.com/*"
]

Manifest V2 vs Manifest V3 Differences

If you’re working with older extensions or need to support Manifest V2, the permission configuration is slightly different:

{
  "permissions": [
    "cookies",
    "*://*.example.com/*"
  ],
  "manifest_version": 2
}

However, we strongly recommend using Manifest V3 for new extensions as it provides better security and performance.

Core Cookie API Methods

The Chrome Cookies API provides several fundamental methods for cookie manipulation. Understanding these methods is essential for building any cookie-related extension functionality.

Retrieving Cookies: chrome.cookies.get

The chrome.cookies.get() method retrieves a single cookie by name from a specific URL:

chrome.cookies.get(
  { url: "https://www.example.com", name: "session_id" },
  (cookie) => {
    if (cookie) {
      console.log("Cookie found:", cookie.value);
      console.log("Cookie domain:", cookie.domain);
      console.log("Cookie secure:", cookie.secure);
      console.log("Cookie httpOnly:", cookie.httpOnly);
    } else {
      console.log("Cookie not found");
    }
  }
);

The method returns a Cookie object with the following properties:

name: The cookie name
value: The cookie value
domain: The domain associated with the cookie
path: The cookie path
secure: Whether the cookie is only sent over secure (HTTPS) connections
httpOnly: Whether the cookie is inaccessible to JavaScript
expirationDate: The expiration date as Unix timestamp
sameSite: The SameSite attribute (strict, lax, or no_restriction)

Retrieving All Cookies: chrome.cookies.getAll

For retrieving multiple cookies, use chrome.cookies.getAll():

chrome.cookies.getAll(
  { domain: ".example.com" },
  (cookies) => {
    cookies.forEach((cookie) => {
      console.log(`${cookie.name}: ${cookie.value}`);
    });
  }
);

You can filter cookies by various criteria:

// Get all cookies for a specific URL
chrome.cookies.getAll(
  { url: "https://www.example.com/dashboard" },
  handleCookies
);

// Get all session cookies (no expiration date)
chrome.cookies.getAll(
  { session: true },
  handleCookies
);

// Get cookies with specific name pattern
chrome.cookies.getAll(
  { name: "pref_" },
  handleCookies
);

Setting Cookies: chrome.cookies.set

Creating or updating cookies is done with chrome.cookies.set():

const cookieDetails = {
  url: "https://www.example.com",
  name: "user_preference",
  value: "dark_mode=true;language=en",
  domain: ".example.com",
  path: "/",
  secure: true,
  httpOnly: false,
  sameSite: "lax",
  expirationDate: Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60) // 30 days
};

chrome.cookies.set(cookieDetails, (cookie) => {
  if (cookie) {
    console.log("Cookie set successfully:", cookie.name);
  } else {
    console.log("Failed to set cookie");
  }
});

Deleting Cookies: chrome.cookies.remove

To delete a specific cookie:

chrome.cookies.remove(
  { url: "https://www.example.com", name: "session_id" },
  (details) => {
    if (details) {
      console.log("Cookie removed:", details.name);
    }
  }
);

Advanced Cookie Management Techniques

Once you understand the basics, you can implement more sophisticated cookie management features in your extensions.

The Chrome Cookies API allows you to monitor cookie changes in real-time using chrome.cookies.onChanged:

chrome.cookies.onChanged.addListener((changeInfo) => {
  const { removed, cookie, cause } = changeInfo;
  
  console.log("Cookie change detected:");
  console.log("  Cookie:", cookie.name);
  console.log("  Removed:", removed);
  console.log("  Cause:", cause);
  console.log("  Domain:", cookie.domain);
  
  if (cookie.name === "session_token" && removed) {
    // Handle session expiration
    notifyUser("Your session has expired. Please log in again.");
  }
});

The cause property can be one of the following values:

explicit: Cookie was set or removed by a script
expired: Cookie expired naturally
evicted: Cookie was evicted to make room for another
expired_overwrite: Cookie was overwritten with an already-expired cookie

Here’s a practical example of building a cookie manager extension:

// background.js - Main cookie management logic

class CookieManager {
  constructor() {
    this.initializeListeners();
  }
  
  initializeListeners() {
    chrome.cookies.onChanged.addListener(this.handleCookieChange.bind(this));
  }
  
  handleCookieChange(changeInfo) {
    const { cookie, removed, cause } = changeInfo;
    
    // Log all cookie changes for debugging
    this.logCookieChange(cookie, removed, cause);
    
    // Update badge to show cookie activity
    this.updateBadge(cookie.domain);
  }
  
  async getAllCookiesForDomain(domain) {
    return new Promise((resolve) => {
      chrome.cookies.getAll(
        { domain: domain },
        (cookies) => resolve(cookies)
      );
    });
  }
  
  async deleteAllCookiesForDomain(domain) {
    const cookies = await this.getAllCookiesForDomain(domain);
    
    for (const cookie of cookies) {
      const url = this.cookieToUrl(cookie);
      await new Promise((resolve) => {
        chrome.cookies.remove(
          { url: url, name: cookie.name },
          resolve
        );
      });
    }
  }
  
  cookieToUrl(cookie) {
    const protocol = cookie.secure ? "https" : "http";
    return `${protocol}://${cookie.domain}${cookie.path}`;
  }
  
  updateBadge(domain) {
    // Update extension badge to show recent activity
    chrome.action.setBadgeText({ text: "✓" });
    setTimeout(() => {
      chrome.action.setBadgeText({ text: "" });
    }, 2000);
  }
  
  logCookieChange(cookie, removed, cause) {
    const logEntry = {
      timestamp: new Date().toISOString(),
      cookieName: cookie.name,
      domain: cookie.domain,
      removed: removed,
      cause: cause
    };
    
    console.log("Cookie change:", logEntry);
  }
}

// Initialize the cookie manager
const manager = new CookieManager();

For extensions that need to synchronize cookies across multiple domains:

async function synchronizeCookies(sourceDomain, targetDomains) {
  // Get cookies from source domain
  const sourceCookies = await new Promise((resolve) => {
    chrome.cookies.getAll(
      { domain: sourceDomain },
      resolve
    );
  });
  
  // Copy each cookie to target domains
  for (const targetDomain of targetDomains) {
    for (const cookie of sourceCookies) {
      const newCookie = {
        url: `https://${targetDomain}`,
        name: cookie.name,
        value: cookie.value,
        domain: cookie.domain.includes(".") ? cookie.domain : "." + targetDomain,
        path: cookie.path,
        secure: cookie.secure,
        httpOnly: cookie.httpOnly,
        sameSite: cookie.sameSite,
        expirationDate: cookie.expirationDate
      };
      
      await new Promise((resolve) => {
        chrome.cookies.set(newCookie, resolve);
      });
    }
  }
}

Best Practices and Security Considerations

When working with the Chrome Cookies API, following best practices ensures your extension remains secure and performs optimally.

Security Guidelines

Always Use Host Permissions Wisely: Only request access to domains that your extension actually needs to interact with. Avoid using <all_urls> unless absolutely necessary.
Prefer Secure Cookies: When setting cookies, always use secure: true for sensitive data:

chrome.cookies.set({
  url: "https://www.example.com",
  name: "auth_token",
  value: sensitiveToken,
  secure: true,
  httpOnly: true,
  sameSite: "strict"
});

Implement SameSite Properly: Use appropriate sameSite settings to prevent CSRF attacks:

// For session cookies - prevents CSRF
chrome.cookies.set({
  url: "https://www.example.com",
  name: "session",
  value: sessionId,
  sameSite: "strict"
});

// For external resources - allows cross-site requests
chrome.cookies.set({
  url: "https://www.example.com",
  name: "tracking",
  value: trackingId,
  sameSite: "no_restriction"
});

Performance Optimization

Minimize Cookie Queries: Instead of querying cookies frequently, cache results and invalidate the cache only when changes occur:

class CookieCache {
  constructor() {
    this.cache = new Map();
    this.cacheExpiry = 5000; // 5 seconds
    
    chrome.cookies.onChanged.addListener(() => {
      this.invalidateCache();
    });
  }
  
  async getCookies(domain) {
    const cacheKey = domain;
    const cached = this.cache.get(cacheKey);
    
    if (cached && Date.now() - cached.timestamp < this.cacheExpiry) {
      return cached.cookies;
    }
    
    const cookies = await new Promise((resolve) => {
      chrome.cookies.getAll({ domain }, resolve);
    });
    
    this.cache.set(cacheKey, {
      cookies,
      timestamp: Date.now()
    });
    
    return cookies;
  }
  
  invalidateCache() {
    this.cache.clear();
  }
}

Use Promises with Async/Await: For better code organization:

function getCookies(url) {
  return new Promise((resolve, reject) => {
    chrome.cookies.getAll({ url }, (cookies) => {
      if (chrome.runtime.lastError) {
        reject(chrome.runtime.lastError);
      } else {
        resolve(cookies);
      }
    });
  });
}

async function handleCookies() {
  try {
    const cookies = await getCookies("https://example.com");
    console.log("Cookies:", cookies);
  } catch (error) {
    console.error("Error getting cookies:", error);
  }
}

Common Use Cases for Cookie Extensions

The Chrome Cookies API enables various practical extension functionalities.

Session Management

Build extensions that help users manage their login sessions:

class SessionManager {
  constructor() {
    this.sessions = new Map();
  }
  
  async createSession(domain, credentials) {
    // Login and store session cookie
    const response = await fetch(`https://${domain}/api/login`, {
      method: "POST",
      body: JSON.stringify(credentials)
    });
    
    const cookies = await new Promise((resolve) => {
      chrome.cookies.getAll({ domain }, resolve);
    });
    
    this.sessions.set(domain, {
      cookies,
      created: Date.now()
    });
    
    return true;
  }
  
  async restoreSession(domain) {
    const session = this.sessions.get(domain);
    if (!session) return false;
    
    // Restore cookies to browser
    for (const cookie of session.cookies) {
      await new Promise((resolve) => {
        chrome.cookies.set({
          url: `https://${domain}`,
          name: cookie.name,
          value: cookie.value,
          domain: cookie.domain,
          path: cookie.path,
          secure: cookie.secure,
          httpOnly: cookie.httpOnly
        }, resolve);
      });
    }
    
    return true;
  }
}

Privacy Controls

Implement privacy-focused features:

class PrivacyManager {
  async blockTrackingCookies() {
    const trackingDomains = [
      "google-analytics.com",
      "facebook.com/tr",
      "doubleclick.net"
    ];
    
    for (const domain of trackingDomains) {
      const cookies = await new Promise((resolve) => {
        chrome.cookies.getAll({ domain }, resolve);
      });
      
      for (const cookie of cookies) {
        await new Promise((resolve) => {
          chrome.cookies.remove({
            url: `https://${cookie.domain}${cookie.path}`,
            name: cookie.name
          }, resolve);
        });
      }
    }
  }
  
  async exportCookies(domain) {
    const cookies = await new Promise((resolve) => {
      chrome.cookies.getAll({ domain }, resolve);
    });
    
    return JSON.stringify(cookies, null, 2);
  }
  
  async importCookies(domain, cookieJson) {
    const cookies = JSON.parse(cookieJson);
    
    for (const cookie of cookies) {
      await new Promise((resolve) => {
        chrome.cookies.set({
          url: `https://${domain}`,
          name: cookie.name,
          value: cookie.value,
          domain: cookie.domain,
          path: cookie.path,
          secure: cookie.secure,
          httpOnly: cookie.httpOnly,
          expirationDate: cookie.expirationDate
        }, resolve);
      });
    }
  }
}

Troubleshooting Common Issues

Even experienced developers encounter issues when working with the Chrome Cookies API. Here are solutions to common problems.

If cookies fail to set, check the following:

Verify URL matches: The URL must match the cookie’s domain and path:

// Wrong
chrome.cookies.set({ url: "https://example.com", name: "test", value: "123" });

// Correct
chrome.cookies.set({ 
  url: "https://www.example.com", 
  name: "test", 
  value: "123",
  domain: ".example.com",
  path: "/" 
});

Check Secure Flag: HTTPS is required for secure cookies:

// This will fail for secure cookies without HTTPS
chrome.cookies.set({
  url: "http://example.com",
  name: "secure_cookie",
  value: "123",
  secure: true
});

Issue: Host Permission Denied

Ensure your manifest correctly declares host permissions:

{
  "host_permissions": [
    "*://*.target-domain.com/*"
  ]
}

Make sure you’ve added the listener correctly:

// Correct: Add listener before using
chrome.cookies.onChanged.addListener((changeInfo) => {
  console.log("Cookie changed");
});

// Not recommended: Adding listener inside callback
chrome.cookies.getAll({}, (cookies) => {
  // Too late to add listener here
});

Conclusion

The Chrome Cookies API is a powerful tool that enables extension developers to create sophisticated cookie management features. From simple cookie readers to complex session managers and privacy controls, understanding this API opens up numerous possibilities for your Chrome extensions.

Remember these key points:

Always use proper host permissions for cookie access
Implement security best practices with secure, httpOnly, and sameSite attributes
Use cookie change listeners for real-time monitoring
Cache results when possible for better performance
Test thoroughly across different domains and cookie configurations

With the knowledge from this guide, you’re now equipped to build powerful cookie management extensions that can handle authentication, sessions, preferences, and privacy controls effectively.

For more information about Chrome extension development, explore our other guides on the Chrome Extension API references and Manifest V3 best practices.

Chrome Extension Local Storage vs Chrome Storage API - Compare different storage options for Chrome extensions
Chrome Extension Storage Patterns for Large Scale Data - Learn advanced storage patterns for data-intensive extensions
Chrome Extension State Management Patterns - Master state management in your extensions

This guide is part of our comprehensive Chrome Extension Development series. For more tutorials and resources, visit our Chrome Extension Guide.

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

Chrome Cookies API Complete Guide for Extensions

Chrome Cookies API Complete Guide for Extensions

Understanding the Chrome Cookies API

What Are Cookies and Why They Matter

The Architecture Behind Cookie Management

Required Permissions and Manifest Configuration

Basic Permission Setup

Understanding Host Permissions

Manifest V2 vs Manifest V3 Differences

Core Cookie API Methods

Retrieving Cookies: chrome.cookies.get

Retrieving All Cookies: chrome.cookies.getAll

Setting Cookies: chrome.cookies.set

Deleting Cookies: chrome.cookies.remove

Advanced Cookie Management Techniques

Cookie Change Listeners

Building a Cookie Manager

Cookie Synchronization Between Domains

Best Practices and Security Considerations

Security Guidelines

Performance Optimization

Common Use Cases for Cookie Extensions

Session Management

Privacy Controls

Troubleshooting Common Issues

Issue: Cookie Not Being Set

Issue: Host Permission Denied

Issue: Cookie Changes Not Detected

Conclusion

Related Articles

This guide is part of our comprehensive Chrome Extension Development series. For more tutorials and resources, visit our Chrome Extension Guide.