Clerk API (unofficial showcase)
PATCH/domains/{domain_id}

Update a domain

The proxy_url can be updated only for production instances. Update one of the instance's domains. Both primary and satellite domains can be updated. If you choose to use Clerk via proxy, use this endpoint to specify the proxy_url. Whenever you decide you'd rather switch to DNS setup for Clerk, simply set proxy_url to null for the domain. When you update a production instance's primary domain name, you have to make sure that you've completed all the necessary setup steps for DNS and emails to work. Expect downtime otherwise. Updating a primary domain's name will also update the instance's home origin, affecting the default application paths. Updating the name or is_secondary of a primary domain 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.

1 parameter · 3 body fields
domain_idstringrequired
The ID of the domain that will be updated.
namestringoptional
The new domain name. For development instances, can contain the port, i.e `myhostname:3000`. For production instances, must be a valid FQDN, i.e `mysite.com`. Cannot contain protocol scheme.
proxy_urlstringoptional
The full URL of the proxy that will forward requests to Clerk's Frontend API. Can only be updated for production instances.
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).

5 status codes
200A domain
objectstringrequired
Allowed:domain
idstringrequired
namestringrequired
is_satellitebooleanrequired
frontend_api_urlstringrequired
accounts_portal_urlstringoptional
Null for satellite domains.
proxy_urlstringoptional
development_originstringrequired
cname_targetsarray<object>optional
Legacy CNAME-only DNS targets. Prefer `dns_targets` when present.
dns_targetsarray<object>optional
The complete typed DNS contract. Consumers should use this field instead of merging it with `cname_targets`.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
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 404 is returned: Resource not found. A 422 is returned: Invalid request parameters.