contextualIdentities

Work with contextual identities: list, create, remove, and update contextual identities.

"Contextual identities", also known as "containers", are a browser feature that lets users assume multiple identities when browsing the web, and maintain some separation between these identities. For example, a user might consider their "work identity" separate from their "personal identity", and not want to share cookies between these two contexts.

With the contextual identities feature, each contextual identity has a name, a color, and an icon. New tabs can be assigned to an identity, and the name, icon, and color appears in the address bar. Internally, each identity gets a cookie store that is not shared with other tabs. This cookie store is identified by thecookieStoreId in this and other APIs.

A context menu with "open in new container tab" submenu highlighted. The submenu shows personal, work, banking, and shopping contextual identities.

Contextual identities are an experimental feature in Firefox and are only enabled by default in Firefox Nightly. To enable them in other versions of Firefox, set theprivacy.userContext.enabled preference totrue. Note that although contextual identities are available in Firefox for Android, there's no UI to work with them in this version of the browser.

Before Firefox 57, thecontextualIdentities API is only available if the contextual identities feature is itself enabled. If an extension tried to use thecontextualIdentities API without the feature being enabled, then method calls would resolve their promises withfalse.

From Firefox 57 onwards, if an extension that uses thecontextualIdentities API is installed, then the contextual identities feature will be enabled automatically. Note though that it's still possible for the user to disable the feature using the "privacy.userContext.enabled" preference. If this happens, thencontextualIdentities method calls will reject their promises with an error message.

See Work with contextual identities for more information.

Contextual identities are not supported in any other browsers.

To use this API you need to include the "contextualIdentities" and "cookies"permissions in yourmanifest.json file.

Types

contextualIdentities.ContextualIdentity: Contains information about a contextual identity.

Functions

contextualIdentities.create(): Creates a new contextual identity.
contextualIdentities.get(): Retrieves a contextual identity, given its cookie store ID.
contextualIdentities.move(): Moves one or more contextual identities within the list of contextual identities.
contextualIdentities.query(): Retrieves all contextual identities, or all contextual identities with a particular name.
contextualIdentities.update(): Updates properties of an existing contextual identity.
contextualIdentities.remove(): Deletes a contextual identity.

Events

contextualIdentities.onCreated: Fired when a contextual identity is created.
contextualIdentities.onRemoved: Fired when a contextual identity is removed.
contextualIdentities.onUpdated: Fired when one or more properties of a contextual identity is updated.