Skip to main content

Change domain

Learn how to change your Clerk production instance's primary domain. You cannot change the domain of the development instance of your Clerk application.

Warning

Changing the domain can result in downtime for your application. This depends on your DNS provider and their propagation times.

Change domain

  1. Update your production domain using either of the following options:
  2. Once you make the change to your domain, you will need to update the following:
    • Update DNS records.
    • Generate new SSL certificates.
    • Update your Publishable Key.
    • If using social connections, update the settings with your social connections so that the redirect URL they are using is correct.
    • If using JWT templates, update JWT issuer and JWKS Endpoint in external JWT SSO services.

Update your domain via Clerk Dashboard

To update your production domain in the Clerk Dashboard:

  1. In the navigation sidenav, select Domains.
  2. Scroll to find the Change domain setting.

Important

If you enter a subdomain of the root domain, for example when moving from example.com to app.example.com, the Change domain dialog will ask whether it should be configured as a Primary application or Secondary application:

  • Select Primary application if users should access your app on the subdomain, but Clerk-related infrastructure should remain on the root domain. In this setup, users still visit your app at app.example.com, but Clerk-hosted URLs and related configuration stay on the root domain. For example:
    • app: app.example.com
    • Clerk: clerk.example.com
  • Select Secondary application if both your app and Clerk should be scoped to the subdomain. In this setup, users still visit your app at app.example.com, and Clerk-hosted URLs and related configuration also live on that subdomain. For example:
    • app: app.example.com
    • Clerk: clerk.app.example.com

Update your domain via Backend API

To update your production domain using the Backend API, you will need to make a POST request to the change_domain endpoint. You will need to provide your new domain in the request body.

  1. Copy the following cURL command.
  1. Replace YOUR_PROD_URL with your new production domain.
terminal
curl -XPOST -H 'Authorization: YOUR_SECRET_KEY' -H "Content-type: application/json" -d '{
"home_url": "YOUR_PROD_URL"
}' 'https://api.clerk.com/v1/instance/change_domain'

For more information on how to update your instance settings using the Backend API, see the Backend API reference.

Update your Publishable Key

After changing your domain, a new will be automatically generated for your application. You need to update your environment variables with this new key and redeploy your application.

Note

Failing to update your Publishable Key will result in Clerk failing to load.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub