From 022f1036798deb3efc164f9066f38422e6eba0be Mon Sep 17 00:00:00 2001 From: "rafael r. camargo" <66796237+rafaelrcamargo@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:27:51 -0300 Subject: [PATCH 1/5] docs(backend): clarify domain migration and deletion --- .changeset/two-aliens-build.md | 5 +++++ packages/backend/src/api/endpoints/DomainApi.ts | 14 ++++++++------ 2 files changed, 13 insertions(+), 6 deletions(-) create mode 100644 .changeset/two-aliens-build.md diff --git a/.changeset/two-aliens-build.md b/.changeset/two-aliens-build.md new file mode 100644 index 00000000000..ccdc6211572 --- /dev/null +++ b/.changeset/two-aliens-build.md @@ -0,0 +1,5 @@ +--- +'@clerk/backend': patch +--- + +Clarify domain API documentation for custom primary domain migration and the restriction on deleting the active domain. diff --git a/packages/backend/src/api/endpoints/DomainApi.ts b/packages/backend/src/api/endpoints/DomainApi.ts index 4e66223048b..329c712e5f1 100644 --- a/packages/backend/src/api/endpoints/DomainApi.ts +++ b/packages/backend/src/api/endpoints/DomainApi.ts @@ -12,7 +12,7 @@ export type AddDomainParams = { * The new domain name. For development instances, can contain the port, e.g., `myhostname:3000`. For production instances, must be a valid FQDN, e.g., `mysite.com`. Cannot contain protocol scheme. */ name: string; - /** Whether the new domain is a satellite domain. Only `true` is accepted at the moment. */ + /** Whether the new domain is a satellite domain. Set to `false` to add the first custom primary domain to a production instance with an active provider domain. */ is_satellite: boolean; /** The proxy URL for the domain. Applicable only to production instances. */ proxy_url?: string | null; @@ -40,7 +40,9 @@ export class DomainAPI extends AbstractAPI { } /** - * Adds a new domain to the instance. Useful in the case of multi-domain instances, allows adding [satellite domains](https://clerk.com/docs/guides/dashboard/dns-domains/satellite-domains) to an instance. + * Adds a [satellite domain](https://clerk.com/docs/guides/dashboard/dns-domains/satellite-domains) or the first custom primary domain to the instance. + * + * To migrate a production instance from an active provider domain to a custom primary domain, set `is_satellite` to `false`. The custom domain becomes active, and the provider domain remains attached. Additional custom primary domains are not supported. * @returns The created [`Domain`](https://clerk.com/docs/reference/backend/types/domain) object. */ public async add(params: AddDomainParams) { @@ -70,8 +72,8 @@ export class DomainAPI extends AbstractAPI { } /** - * Deletes a satellite domain for the instance. It is currently not possible to delete the instance's primary domain. - * @param satelliteDomainId - The ID of the satellite domain to delete. + * Deletes a domain for the instance. The active domain cannot be deleted. + * @param satelliteDomainId - The ID of the domain to delete. * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object). */ public async delete(satelliteDomainId: string) { @@ -79,8 +81,8 @@ export class DomainAPI extends AbstractAPI { } /** - * Deletes a satellite domain for the instance. - * @param satelliteDomainId - The ID of the satellite domain to delete. + * Deletes a domain for the instance. The active domain cannot be deleted. + * @param satelliteDomainId - The ID of the domain to delete. * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object). * @deprecated Use `delete()` instead. */ From c6f8551f2bd14fb7408c058755a2099f185571a1 Mon Sep 17 00:00:00 2001 From: "rafael r. camargo" <66796237+rafaelrcamargo@users.noreply.github.com> Date: Mon, 14 Sep 2026 16:00:32 -0300 Subject: [PATCH 2/5] chore(ci): retrigger checks From 5766b3a60472c210bf81f99870ba3ec11fe7cb95 Mon Sep 17 00:00:00 2001 From: "rafael r. camargo" <66796237+rafaelrcamargo@users.noreply.github.com> Date: Tue, 15 Sep 2026 16:58:12 -0300 Subject: [PATCH 3/5] docs(backend): use generic domain IDs in deletion signatures --- packages/backend/src/api/endpoints/DomainApi.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/backend/src/api/endpoints/DomainApi.ts b/packages/backend/src/api/endpoints/DomainApi.ts index 329c712e5f1..11bb0c15cba 100644 --- a/packages/backend/src/api/endpoints/DomainApi.ts +++ b/packages/backend/src/api/endpoints/DomainApi.ts @@ -73,24 +73,24 @@ export class DomainAPI extends AbstractAPI { /** * Deletes a domain for the instance. The active domain cannot be deleted. - * @param satelliteDomainId - The ID of the domain to delete. + * @param domainId - The ID of the domain to delete. * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object). */ - public async delete(satelliteDomainId: string) { - return this.deleteDomain(satelliteDomainId); + public async delete(domainId: string) { + return this.deleteDomain(domainId); } /** * Deletes a domain for the instance. The active domain cannot be deleted. - * @param satelliteDomainId - The ID of the domain to delete. + * @param domainId - The ID of the domain to delete. * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object). * @deprecated Use `delete()` instead. */ - public async deleteDomain(satelliteDomainId: string) { - this.requireId(satelliteDomainId); + public async deleteDomain(domainId: string) { + this.requireId(domainId); return this.request({ method: 'DELETE', - path: joinPaths(basePath, satelliteDomainId), + path: joinPaths(basePath, domainId), }); } } From d99cc81683499440996566a05bdad1ad00f3d2c7 Mon Sep 17 00:00:00 2001 From: "rafael r. camargo" <66796237+rafaelrcamargo@users.noreply.github.com> Date: Tue, 15 Sep 2026 19:07:24 -0300 Subject: [PATCH 4/5] docs(backend): replace internal domain terminology --- packages/backend/src/api/endpoints/DomainApi.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/backend/src/api/endpoints/DomainApi.ts b/packages/backend/src/api/endpoints/DomainApi.ts index 11bb0c15cba..80d1d6a14af 100644 --- a/packages/backend/src/api/endpoints/DomainApi.ts +++ b/packages/backend/src/api/endpoints/DomainApi.ts @@ -12,7 +12,7 @@ export type AddDomainParams = { * The new domain name. For development instances, can contain the port, e.g., `myhostname:3000`. For production instances, must be a valid FQDN, e.g., `mysite.com`. Cannot contain protocol scheme. */ name: string; - /** Whether the new domain is a satellite domain. Set to `false` to add the first custom primary domain to a production instance with an active provider domain. */ + /** Whether the new domain is a satellite domain. Set to `false` when migrating a production instance from a `.vercel.app` or `.replit.app` domain to its first custom primary domain. */ is_satellite: boolean; /** The proxy URL for the domain. Applicable only to production instances. */ proxy_url?: string | null; @@ -42,7 +42,7 @@ export class DomainAPI extends AbstractAPI { /** * Adds a [satellite domain](https://clerk.com/docs/guides/dashboard/dns-domains/satellite-domains) or the first custom primary domain to the instance. * - * To migrate a production instance from an active provider domain to a custom primary domain, set `is_satellite` to `false`. The custom domain becomes active, and the provider domain remains attached. Additional custom primary domains are not supported. + * To replace a production instance's `.vercel.app` or `.replit.app` primary domain with a custom primary domain, set `is_satellite` to `false`. The custom domain becomes the instance's active domain, and the original domain remains attached. Additional custom primary domains are not supported. * @returns The created [`Domain`](https://clerk.com/docs/reference/backend/types/domain) object. */ public async add(params: AddDomainParams) { From 65bf757c7e6fc08276b3f52cb41770682d860096 Mon Sep 17 00:00:00 2001 From: "rafael r. camargo" <66796237+rafaelrcamargo@users.noreply.github.com> Date: Thu, 17 Sep 2026 14:30:43 -0300 Subject: [PATCH 5/5] docs(backend): simplify domain API documentation --- .changeset/two-aliens-build.md | 2 +- packages/backend/src/api/endpoints/DomainApi.ts | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/.changeset/two-aliens-build.md b/.changeset/two-aliens-build.md index ccdc6211572..06a7f0aeaf8 100644 --- a/.changeset/two-aliens-build.md +++ b/.changeset/two-aliens-build.md @@ -2,4 +2,4 @@ '@clerk/backend': patch --- -Clarify domain API documentation for custom primary domain migration and the restriction on deleting the active domain. +Clarify domain API documentation and deletion parameter names. The active domain cannot be deleted. diff --git a/packages/backend/src/api/endpoints/DomainApi.ts b/packages/backend/src/api/endpoints/DomainApi.ts index 80d1d6a14af..89fa03b11ff 100644 --- a/packages/backend/src/api/endpoints/DomainApi.ts +++ b/packages/backend/src/api/endpoints/DomainApi.ts @@ -12,7 +12,7 @@ export type AddDomainParams = { * The new domain name. For development instances, can contain the port, e.g., `myhostname:3000`. For production instances, must be a valid FQDN, e.g., `mysite.com`. Cannot contain protocol scheme. */ name: string; - /** Whether the new domain is a satellite domain. Set to `false` when migrating a production instance from a `.vercel.app` or `.replit.app` domain to its first custom primary domain. */ + /** Whether the new domain is a satellite domain. */ is_satellite: boolean; /** The proxy URL for the domain. Applicable only to production instances. */ proxy_url?: string | null; @@ -40,9 +40,7 @@ export class DomainAPI extends AbstractAPI { } /** - * Adds a [satellite domain](https://clerk.com/docs/guides/dashboard/dns-domains/satellite-domains) or the first custom primary domain to the instance. - * - * To replace a production instance's `.vercel.app` or `.replit.app` primary domain with a custom primary domain, set `is_satellite` to `false`. The custom domain becomes the instance's active domain, and the original domain remains attached. Additional custom primary domains are not supported. + * Adds a new domain to the instance. Useful in the case of multi-domain instances, allows adding [satellite domains](https://clerk.com/docs/guides/dashboard/dns-domains/satellite-domains) to an instance. * @returns The created [`Domain`](https://clerk.com/docs/reference/backend/types/domain) object. */ public async add(params: AddDomainParams) {