Guides

Connecting Customer Domains

Give every tenant a branded experience by letting them point their own domain at AuthCore. The platform keeps the legacy Organization.customDomain column working while promoting the new OrganizationDomain model for multi-domain support.

How default and custom domains work together

Every request runs through the same resolver so you can mix default subdomains with branded hosts without breaking anything. The lookup order is:

  1. Verified custom domains — The new OrganizationDomain table stores every hostname a tenant has verified. Any exact match instantly hydrates req.organization.
  2. Legacy single-domain field — Existing installs that still rely on Organization.customDomain continue to function. The resolver checks this column so upgrades are backward compatible.
  3. Default platform domain — When no explicit mapping is found, AuthCore falls back to the tenant slug prefix (for example acme.your-auth-domain.com). This keeps the out-of-the-box domain alive for every organization.
Once a tenant verifies a custom hostname, the default subdomain still works. You can safely link to acme.your-auth-domain.com in emails while giving paying customers login.acme.com for a white-labeled feel.

1. Request a verification token

Call the new API endpoint from your dashboard when a customer submits a hostname. It normalizes the string, checks for conflicts, and issues a token that must live in a TXT record at the root of the requested domain.

POST /api/organizations/:orgId/domains

Store the response so that you can remind customers of the DNS steps: add authcore-verification=<token> as a TXT record, wait for propagation, and then run verification.

2. Verify DNS ownership

Re-hit the API after DNS propagates. AuthCore looks up TXT records and flips the verified flag once the token appears. The handler returns a friendly message when the record is still missing so you can retry without throwing errors in the UI.

POST /api/organizations/:orgId/domains/verify
Propagation tip: upstream DNS providers sometimes cache results for five to ten minutes. Expose a manual refresh button so admins can re-run verification without resubmitting the hostname.

3. Route traffic by host header

The public middleware now inspects the incoming host, queries OrganizationDomain, and hydrates req.organization. Drop in the snippet below to branch logic or send custom analytics events whenever a custom domain is in play.

middleware.ts

Legacy single-domain customers continue to resolve through Organization.customDomain, so you can ship this routing upgrade without forcing an immediate migration.

Migrating existing data

Run the helper script once after deploying the Prisma migration. It copies any populated customDomain values into the new table so that verification can be re-run and ownership maintained.

scripts/migrate-legacy-domains.js
Checklist: 1) npx prisma migrate deploy 2) npx prisma generate 3) node scripts/migrate-legacy-domains.js in each environment.