Clerk API (unofficial showcase)
POST/instance/change_domain

Update production instance domain

Change the domain of a production instance.

Changing the domain requires updating the DNS records accordingly, deploying new SSL certificates, updating your Social Connection's redirect URLs and setting the new keys in your code.

WARNING: Changing your domain will invalidate all current user sessions (i.e. users will be logged out). Also, while your application is being deployed, a small downtime is expected to occur.

Returns 403 domain_managed_by_integration for applications in a Vercel-managed workspace; change the domain from the Vercel integration instead.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 body fields
home_urlstringoptional
The new home URL of the production instance e.g. https://www.example.com
is_secondarybooleanoptional
Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and will be stored as part of the domain. This is useful for supporting multiple apps (one primary and multiple secondaries) on the same root domain (eTLD+1).

4 status codes
202Accepted
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 403 is returned: Request was not successful. A 422 is returned: Request was not successful.