Authentication across different domains
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 the sign-in flow on the primary domain, either using Clerk’s <SignIn />
component or useSignIn()
hook.
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.
How to add satellite domains
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
.
Add your first satellite domain
To add a satellite domain:
- Navigate to the Clerk Dashboard
- In the navigation sidebar, select Domains.
- Select the Satellite tab.
- Select the Add satellite domain button and follow the instructions provided.
For the purposes of this guide:
- In production, the satellite domain will be
satellite.dev
. - In development, the satellite domain will be
localhost:3001
.
Configure your satellite app
There are two ways that you can configure your Clerk satellite application to work with the primary domain:
- Using environment variables
- Using properties
Configure your satellite app with environment variables
You can configure your satellite application by setting the following environment variables:
In development, your publishable and secret keys will start with
pk_test_
andsk_test
respectively.
Configure your satellite app with properties
You can configure your satellite application as a satellite application by setting the isSatellite
, domain
, and signInUrl
properties.
The properties related to the multi-domain setup are:
- Name
isSatellite
- Type
boolean
or(url: URL) => boolean
- Description
This option defines that the application is a satellite application.
- Name
domain
- Type
string
or(url: URL) => boolean
- Description
This option 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.
- Name
signInUrl
- Type
string
- Description
This url will be used for any redirects that might happen and needs to point to your primary application. This option is optional for production instances and required for development instances.
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 a Next.js application, you must set the properties in the <ClerkProvider>
component and in your authMiddleware()
.
Configuring your <ClerkProvider>
component should look like this:
And your middleware should look like this:
In a Remix application, you must set the properties in the ClerkApp
wrapper.
Ready to go 🎉
Your satellite application should now be able to access the authentication state from your satellite domain!
You can see it in action by:
- Visiting the primary domain and signing in.
- Visiting the satellite domain.
- You now have an active session in the satellite domain, so you can see the
<UserProfile />
component and update your information.
You can repeat this process and create as many satellite applications as you need.
You can also check out the example repository with a primary and a satellite Next.js application.
If you have any questions about satellite domains, or you're having any trouble setting this up, please contact support@clerk.com
Feedback
Last updated on