Skip to main content
Docs

Authentication across different domains

Warning

This guide addresses authentication across different domains with shared sessions. For example, example-site.com and example-site-admin.com.

Authentication across subdomains with shared sessions works by default with Clerk.

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.

How to add satellite domains

Warning

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.

Warning

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.

Add your first satellite domain

To add a satellite domain:

  1. In the Clerk Dashboard, navigate to the Domains page.
  2. Select the Satellites tab.
  3. 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

Use the following tabs to select your preferred method. Clerk recommends using environment variables.

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:

    .env
    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
    CLERK_SECRET_KEY=YOUR_SECRET_KEY
    NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
    NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
  • In the .env file associated with your other (satellite) domain:

    .env
    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
    CLERK_SECRET_KEY=YOUR_SECRET_KEY
    NEXT_PUBLIC_CLERK_IS_SATELLITE=true
    # Production example:
    NEXT_PUBLIC_CLERK_DOMAIN=satellite.dev
    NEXT_PUBLIC_CLERK_SIGN_IN_URL=https://primary.dev/sign-in
    NEXT_PUBLIC_CLERK_SIGN_UP_URL=https://primary.dev/sign-up
    
    # Development example:
    # NEXT_PUBLIC_CLERK_DOMAIN=http://localhost:3001
    # NEXT_PUBLIC_CLERK_SIGN_IN_URL=http://localhost:3000/sign-in
    # NEXT_PUBLIC_CLERK_SIGN_UP_URL=http://localhost:3000/sign-up
  • 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:

    app/layout.tsx
    import { ClerkProvider } from '@clerk/nextjs'
    
    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body>
            <ClerkProvider allowedRedirectOrigins={['http://localhost:3001']}>{children}</ClerkProvider>
          </body>
        </html>
      )
    }

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:

  1. Visiting the primary domain and signing in.
  2. Visiting the satellite domain.
  3. 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.

If you have any questions about satellite domains, or you're having any trouble setting this up, contact

Feedback

What did you think of this content?

Last updated on