Docs

Change domain or subdomain

Learn how to change your Clerk production instance's domain or subdomain.

Note

You cannot change the domain of the development instance of your Clerk application.

Change domain

  1. Update your production domain in two ways:
  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 sidebar, select Domains.
  2. Select the Danger tab.
  3. Select Change domain.

Update your domain via backend API

To update your production domain using Clerk's 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 our backend API reference.

Update your publishable key

After changing your domain, a new Publishable key will be automatically generated for your application. You will need to update your environment variables with this new key and redeploy your application. You can find your Publishable key on the API Keys page of the Clerk Dashboard.

Note

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

Set, change, or remove subdomain

To set, change, or remove a subdomain for your production instance:

  1. Navigate to the Clerk Dashboard.
  2. In the navigation sidebar, select Domains.
  3. Select the Danger tab.
  4. You will see the Change subdomain section where you can set, change, or remove your subdomain.

Feedback

What did you think of this content?

Last updated on