Team & Settings

Custom Domains

Routebase works with your domains in two places: verified organization domains prove you own an email domain, which claims it for your organization and unlocks SSO enforcement for its users, and documentation portal addresses control where your published docs are served. This guide covers both.

Verified organization domains

Verified domains have their own page: Settings → Domains (in the Security group of the settings sidebar), described as "Verify your email domains to claim them for this organization and protect against shadow workspaces." Managing them requires the org:manage-security permission, which Admins and Owners have.

There is no plan requirement — domain verification is available on every plan, because claiming your domain is protection against someone opening a workspace behind your back, not a premium feature. What is Enterprise-only is SSO enforcement, which builds on a verified domain; see Single Sign-On.

Adding a domain

  1. Click Add domain.
  2. Enter a root domain like acme.com — no scheme (https://) or path. Subdomains such as docs.acme.com are also accepted.
  3. Click Add domain to register it. The domain appears in the list with a Pending verification badge.

Verifying ownership via DNS

A newly added domain shows a verification panel with the DNS TXT record you need to publish:

Field Value
Host the record name shown in the panel (copy button provided)
Type TXT
Value a unique verification string (copy button provided)

Create that record in your DNS provider, then click I've added the record — Verify now. DNS propagation may take a few minutes, so if verification fails right away, wait and retry.

Domain status

Each domain in the list shows when it was added and verified, plus one of three status badges:

Badge Meaning
Pending verification The TXT record hasn't been confirmed yet.
Verified Ownership is proven — the domain is claimed for your organization (see below); SSO enforcement is available but off.
SSO required Users on this domain must sign in via SSO.

Once a domain is verified, an SSO required switch appears next to it — see Enforcing SSO for what happens to existing password users when you turn it on. Enforcement needs an active SSO connection, so it is only useful on Enterprise; everything described under What verifying a domain claims applies on every plan.

To delete a domain, open its ⋯ menu and choose Remove domain. Any SSO enforcement for that domain is disabled, and the domain stops being claimed.

What verifying a domain claims

A verified domain belongs to your organization across all of Routebase. Two things follow from that:

Nobody else can found an organization on it. Someone signing up with an address under your verified domain cannot create their own separate workspace. The onboarding wizard tells them on entry, and the same check runs again when the organization would actually be created: "acme.com belongs to Acme Inc. Contact their administrator to get invited." This is what keeps an ex-employee — or a well-meaning colleague in another department — from starting a shadow workspace under your company's name.

Being blocked is not being added. There is no automatic join: the person is pointed at your administrator and has to be invited like anyone else, or sign in through an active SSO connection with just-in-time provisioning enabled. Verifying a domain never pulls existing accounts into your organization either.

A verified domain also has an effect at the other end of the membership: someone whose address is on one of your verified domains loses their sign-in when they leave your organization, while external collaborators on their own domains do not. See Organization Settings.

Only verified domains claim anything. A domain still showing Pending verification has no effect at all — adding one costs nothing and proves nothing.

Documentation portal addresses

Each published documentation portal has its own public address, managed per portal in its settings page — see Publishing documentation for the full publishing flow.

Portal subdomain

The Portal Subdomain card sets your portal's default public address — a subdomain under docs.routebase.dev (for example, acme-webshop-docs.docs.routebase.dev). Enter a name and click Save:

  • 3–63 characters; only lowercase letters, numbers, and single hyphens.
  • Must be globally unique across Routebase.
  • Saving requires the docs:manage-portal permission.

Your portal is reachable at this subdomain once published. If your portal is built but has no subdomain yet, its settings page tells you: "Your portal is built but isn't publicly reachable yet."

Custom domain

The Custom Domain card ("Serve your documentation portal on your own domain") lets you serve the portal on a domain you own, with your own DNS records and an automatically issued SSL certificate. It sits directly below the Portal Subdomain card and requires the docs:manage-portal permission.

Custom domains are a Pro or Enterprise feature. On the Free or Starter plan — and during a Pro trial, which does not include custom domains — the card shows an upgrade prompt instead: "Custom domains are available on the Pro plan. Upgrade to serve your documentation portal on your own domain with automatic SSL." with an Available on Pro — Upgrade button. (The backend enforces this too; unpaid requests are rejected.)

Setting up a custom domain

The card walks you through a short sequence of steps:

  1. Enter your domain. Type a subdomain you own — for example docs.example.com — and click Add domain. (The helper text notes: "Enter a subdomain you own, e.g. docs.example.com. You'll add DNS records next.")
  2. Add the DNS records. The card then shows the records to create at your DNS provider: a CNAME and a TXT record, each with its Name and Value and a copy button. Above them: "Add these DNS records for docs.example.com at your DNS provider, then verify." DNS changes can take a few minutes to propagate.
  3. Verify DNS. Click Verify DNS. If a record isn't found yet, the card reports the granular result — CNAME and TXT each get a Found/Not found badge — so you know which record still needs to propagate.
  4. Activate (provision SSL). Once DNS is verified ("DNS verified for docs.example.com. Activate to issue the SSL certificate."), click Activate (provision SSL). Issuing the certificate can take a few minutes.
  5. Active. When the certificate is live, the card shows "Your portal is live at" with a link to your domain, plus a Domain Health readout: DNS and SSL each as a Valid/Invalid badge, the last-checked time, any error detail, and a Check now button to re-run the check on demand.

At every step a Remove button lets you drop the domain; your portal then falls back to its default routebase.dev address.

If your plan changes

If your subscription later drops below Pro (a downgrade or cancellation), the custom domain is suspended rather than deleted, and the portal falls back to its {subdomain}.docs.routebase.dev address. The card explains: your domain "is suspended because your plan no longer includes custom domains. Upgrade to Pro to reactivate it automatically — your DNS records stay configured, no re-verification needed." Re-upgrading reactivates the domain automatically — because the DNS records stay in place, you don't have to verify DNS again.