Custom Domains

Every workspace gets a family of system subdomains under bettersuite.io automatically. You can layer your own domains on top of them. This article walks through what's mapped, the one DNS record you add, and what happens between adding a domain and it going live.

What gets provisioned by default

When your workspace is created, BetterSuite generates one system subdomain per app from your slug plus a per-app suffix:

Only the apps for verticals you enabled get provisioned, plus ADMIN_CONSOLE always. ADMIN_CONSOLE is your console address: this same dashboard, under your own name and logo and limited to your workspace. System subdomains are pre-verified and can't be removed from the dashboard — they're the fallback if a custom domain regresses.

Changing your slug

The slug is the part of every system subdomain that is yours, so changing it moves all of them at once. The Owner does it under Settings → Workspace → Web address → Change, after re-entering their password. Admins see the addresses but not the button.

What happens when you change it:

• Every system subdomain moves to the new slug. acme-rides.bettersuite.io becomes acmecabs-rides.bettersuite.io, and likewise for each app and for your console address.
• The old addresses keep working. They redirect to the same page on the new address, so links, QR codes and bookmarks already in circulation still land. Allow up to five minutes for every old address to switch over.
• The old slug stays yours. No other workspace can register it, and you can change back to it later.
• Custom domains are not touched. They stay verified and keep serving. The one exception is a custom domain you front with a proxy of your own: it still forwards to an old address, so the dashboard lists it afterwards with the new address to point the proxy at.
• People sign in again on the web. The new addresses are new origins to a browser, so customers and staff who were signed in to a web app or to your console address are asked to sign in once more. Installed mobile apps are unaffected.
• Passkeys saved on an old address stop matching. A customer who signs in with a passkey is asked for a code instead, and can save a new passkey afterwards. Owner and admin passkeys are not affected.

You can change the slug once every 30 days. The dialog checks the slug as you type and shows the addresses your apps would get before you confirm. A slug is 3–40 lowercase letters, digits and single hyphens, and can't start or end with a hyphen.

What a custom domain replaces

A custom domain is added per app. The page is at Owner Dashboard → Custom Domains and is owner-only — non-owner admins can't add or remove domains even if they have other manage-* permissions.

Each app card shows the system subdomain on top and either a custom-domain block underneath or an "Add custom domain" button.

How a custom domain goes live

You add one DNS record. BetterSuite does the rest: it validates the domain, issues its HTTPS certificate, renews it, and routes the domain to the right app. There is no server of your own to run in front of it.

Every custom domain, for every app, points at the same target:

The dashboard shows this target on the app card, with a copy button, both before you add the domain and while it is pending.

Once the record is visible, the domain is validated over HTTP and its certificate is issued — usually within a few minutes. Until then the domain shows as Pending, with the reason underneath (for example, that the DNS record hasn't been seen yet, or that the certificate is being issued).

Passkeys, iOS Universal Links and Android App Links work on the custom domain without any extra setup: the /.well-known/ files they rely on are served for it automatically.

Workflow end to end

1. Open Owner Dashboard → Custom Domains and click Add custom domain on the app card.
2. Enter the hostname (e.g. rides.acme.com) and add it. It appears as Pending. You can do this before the DNS record exists.
3. Add the CNAME at your DNS provider, pointing to domains.bettersuite.io.
4. Click the refresh icon next to the Pending badge after a few minutes. It flips to Verified once the certificate is live; until then it tells you what it is still waiting on.

Removing a custom domain

The trash icon next to a custom domain triggers a step-up password prompt before deletion — removing a domain in production redirects live traffic, and a hijacked session shouldn't be able to do that without re-entering the password. System domains can't be deleted; they're managed automatically.

Removed domains are written to the audit log (/dashboard/audit-log) as custom_domain_removed, with the domain string in the payload, so you can answer "who took rides.acme.com offline?" later.

Common issues

• Pending says the domain "does not CNAME to this zone" — the record is missing, points somewhere else, or hasn't propagated. Check it with dig CNAME rides.acme.com; it must answer domains.bettersuite.io.
• CAA records blocking issuance — if your domain publishes a restrictive CAA record, the certificate can't be issued and the pending reason says so. Allow issuance for the subdomain you're pointing at us.
• Your DNS is on Cloudflare — set the record to DNS only (grey cloud). A proxied record in your own Cloudflare account hides the CNAME from validation.
• System-suffix collision — you can't register a custom domain ending in .bettersuite.io; the mutation rejects it explicitly.

What's next

• Branding — pair your custom hostname with your own logos and theme.
• Team & Roles — control which admins can manage domains.