Clerk Chrome Extension SDK

The Clerk Chrome Extension SDK is the recommended method for integrating Clerk into your Chrome Extension.

Authentication options

When creating your Clerk application in the Clerk Dashboard, your authentication options will depend on how you configure your Chrome Extension. You can configure your Chrome Extension to behave as one of the following:

• Popup - Opens as a popup. This is the default behavior.
• Side Panel - Opens in a side panel
• Sync Host - Deployed alongside a web app that uses Sync Host.

See the following table to determine the authentication options available for each configuration.

Sync auth status between your Chrome Extension and web app

Clerk allows you to sync the authentication state from your web app to your Chrome Extension using the Sync Host feature. When a user authenticates in your web app, they will also be authenticated in your Chrome Extension. See the dedicated guide for more information.

createClerkClient()

It's recommended to use createClerkClient() for Chrome Extension's that need to interact with Clerk in a content script.

The createClerkClient() helper initializes a new Clerk instance on demand and refreshes the session token if there is a valid, signed-in user. It can be used in a content script⁠ or a background service worker⁠ to access a user's information or session token. Learn more about createClerkClient().

Add React Router

Learn how to add React Router to your Chrome Extension to enable routing in your application.

Deploy your extension to production

See the Chrome Extension deployment guide for information about deploying your extension to production.

Configure a consistent CRX ID

A Chrome Extension can be identified by its unique CRX ID, similar to how a website can be identified by its domain. The CRX ID rotates by default, which can cause errors with the Clerk integration. Learn how to configure a consistent CRX ID so that your extension will have a stable, unchanging key.

Frequently asked questions (FAQ)

Can I use Clerk in a content script?

Unfortunately, no. Clerk has strict security restrictions on the allowed origins for requests from the application or extension to Clerk's API. Since a content script could run on any domain, there is no way to enforce origin restrictions.

Why can't I use OAuth, SAML, or Email Links with the extension popup or side panel?

OAuth and SAML require a redirect back from the Identity Provider (IdP), which is not currently supported in popups or side panels.

Email Links require the popup to remain open while the user checks their email, copies the link, and returns to paste it. Since popups close as soon as a user clicks outside of them, this flow is not possible. The sign-in status resets when the popup closes.

Why aren't options like Google One Tap or Web3 available in a popup or side panel?

Chrome Extensions can't load code from remote sources. Features like Google One Tap, Web3, and some other authentication options require loading remote code to function. This functionality is removed from the Chrome Extension SDK to ensure extensions using Clerk are not rejected by the Chrome Web Store.