Clerk API (unofficial showcase)
POST/domains

Add a domain

Add a new domain for your instance. Useful in the case of multi-domain instances, allows adding satellite domains to an instance. The new domain must have a name. The domain name can contain the port for development instances, like localhost:3000. Set is_satellite to true to add a satellite domain. To migrate a production instance from an active provider domain to its first custom primary domain, set is_satellite to false. The custom domain becomes active and the provider domain stays attached. Additional custom primary domains are not supported. If you're planning to configure the new satellite domain to run behind a proxy, pass the proxy_url parameter accordingly. Adding a custom 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.

3 body fields
namestringrequired
The new domain name. Can contain the port for development instances.
is_satellitebooleanrequired
Marks the new domain as satellite. Set to `false` only when migrating a production instance from an active provider domain to a custom domain.
proxy_urlstringoptional
The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. Applicable only to production instances.

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
402Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Request was not successful
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 402 is returned: Request was not successful. A 403 is returned: Request was not successful. A 422 is returned: Invalid request parameters.