Clerk supports sharing sessions across different domains by adding one or many satellite domains to an application.
Your "primary" domain is where the authentication state lives, and satellite domains are able to securely read that state from the primary domain, enabling a seamless authentication flow across domains.
Users must complete both the sign-in and sign-up flows on the primary domain by using the <SignIn /> component or useSignIn() hook for sign-in and <SignUp /> component or useSignUp() hook for sign-up.
To access authentication state from a satellite domain, users will be transparently redirected to the primary domain. If users need to sign in, they must be redirected to a sign in flow hosted on the primary domain, then redirected back to the originating satellite domain. The same redirection process applies to sign-up flows.
This feature is not available in production for free plans, though you can try it out free in development to see if it works for you. See the pricing page for more information.
Currently, multi-domain can be added to any Next.js or Remix application. For other React frameworks, multi-domain is still supported as long as you do not use server rendering or hydration.
To get started, you need to create an application from the Clerk Dashboard. Once you create an instance via the Clerk Dashboard, you will be prompted to choose a domain. This is your primary domain. For the purposes of this guide:
In production, the primary domain will be primary.dev
In development, the primary domain will be localhost:3000.
When building your sign-in flow, you must configure it to run within your primary application, e.g. on /sign-in.
Note
For more information about creating your application, see the setup guide.
There are two ways that you can configure your Clerk satellite application to work with the primary domain:
Using environment variables
Using properties
Use the following tabs to select your preferred method. Clerk recommends using environment variables.
Environment variables
Properties
You can configure your satellite application by setting the following environment variables:
Note
In development, your Publishable and Secret Keys will start with pk_test_ and sk_test respectively.
In the .env file associated with your primary domain:
Next.js
Remix
In the .env file associated with your other (satellite) domain:
Next.js
Remix
You will also need to add the allowedRedirectOrigins property to <ClerkProvider /> on your primary domain app to ensure that the redirect back from primary to satellite domain works correctly. For example:
Development
Production
You can configure your satellite application by setting the following properties:
isSatellite - Defines the app as a satellite app when true.
domain - Sets the domain of the satellite application. This is required since we cannot figure this out by your Publishable Key, since it is the same for all of your multi-domain apps.
signInUrl - This url will be used when signing in on your satellite application and needs to point to your primary application. This option is optional for production instances and required for development instances.
signUpUrl - This url will be used for signing up on your satellite application and needs to point to your primary application. This option is optional for production instances and required for development instances.
allowedRedirectOrigins - This is a list of origins that are allowed to redirect back to from the primary domain.
Tip
The URL parameter that can be passed to isSatellite and domain is the request url for server-side usage or the current location for client usage.
In the Next project associated with your primary domain, only the signInUrl prop needs to be configured as shown in the following example:
Important
You should set your CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY in your environment variables even if you're using props to configure satellite domains.
App Router
Pages Router
In the Next project associated with your satellite domain, configure your <ClerkProvider> as shown in the following example:
App Router
Pages Router
And the middleware associated with your satellite domain should look like this:
In a Remix application, you must set the properties in the ClerkApp wrapper.
In the root file associated with your primary domain, you only need to configure the signInUrl prop:
In the root file associated with your satellite domain, configure ClerkApp as shown in the following example: