The Contextual Identity API and Firefox Container Tabs

This article explores the Contextual Identity WebExtensions API, a powerful feature unique to the Mozilla Firefox web browser. It covers the fundamental architecture of the API, how it isolates user data to power the "Container Tabs" feature, and the core programmatic functions developers use to build privacy-focused and session-management extensions. By understanding this API, you will see how Firefox allows users to maintain multiple, separate digital identities within a single browser window.

What is the Contextual Identity WebExtensions API?

The Contextual Identity API (browser.contextualIdentities) is a Firefox-specific WebExtensions API that allows extension developers to manage different browsing contexts within the same browser profile.

In standard web browsing, all open tabs share the same storage space. If you log into a website in one tab, you are logged into that same website in every other tab. The Contextual Identity API breaks this rule by allowing the browser to create isolated storage environments, known as contextual identities. Each identity acts as a separate "cookie jar" with its own unique identifier.

How the API Powers Container Tabs

To the end-user, a contextual identity is known as a Container Tab. Mozilla’s popular extensions, such as "Firefox Multi-Account Containers" and "Facebook Container," are built directly on top of this API.

Here is how the API powers the container mechanism under the hood:

  • The cookieStoreId Property: Every tab in Firefox is assigned a cookieStoreId. Standard tabs use the default ID, and private browsing tabs use a private ID. When a new contextual identity is created via the API, Firefox generates a new, unique cookieStoreId (e.g., firefox-container-1).
  • Storage Isolation: When a tab is opened with a specific cookieStoreId, Firefox isolates all site data for that tab. Cookies, localStorage, indexedDB, and HTTP cache data are strictly bound to that specific ID. One container cannot read or access the cookies or storage of another container.
  • Shared Browser Profile: Unlike full browser profiles, which separate everything, Contextual Identities only isolate site data. Container tabs still share the user's global bookmarks, browsing history, saved passwords, and installed extensions. This makes switching between contexts seamless without needing to open a new browser window or configure a new profile.
  • Visual Indicators: The API allows developers to assign a specific name, color, and icon to each cookieStoreId. Firefox uses these properties to render a colored stripe along the top of the tab and an icon in the address bar, visually informing the user which container is currently active.

Core Capabilities for Developers

To use the Contextual Identity API, an extension must explicitly request the contextualIdentities and cookies permissions in its manifest.json file. Once granted, the extension can control containers using several straightforward methods:

  • browser.contextualIdentities.create(): Creates a new container with a specified name, color, and icon, returning an object containing the newly generated cookieStoreId.
  • browser.contextualIdentities.query(): Retrieves information about all existing containers, or filters them by specific properties like name.
  • browser.contextualIdentities.update(): Modifies the name, color, or icon of an existing container using its cookieStoreId.
  • browser.contextualIdentities.remove(): Deletes a container and wipes all cookies and site data associated with its cookieStoreId.

To actually open a tab inside a container, developers combine the Contextual Identity API with the Tabs API. By calling browser.tabs.create() and passing the container's cookieStoreId as a parameter, the browser opens the requested URL inside that isolated environment.

Practical Use Cases

By leveraging the Contextual Identity API, developers have solved two major modern web browsing problems:

  1. Multi-Account Management: Users can log into multiple accounts on the same platform simultaneously. For example, a user can open their work email in a "Work" container and their personal email in a "Personal" container right next to it, without the sessions conflicting.
  2. Anti-Tracking and Privacy: Extensions can automatically route specific websites into dedicated containers. If a social media site is locked into its own container, the tracking cookies it places on your browser are trapped in that cookieStoreId. When you visit other websites in your default tabs, the social media platform cannot use its cookies to track your browsing activity across the web.