Skip to main content

Domains

Domains let a tenant advertise one or more custom addresses through which users reach their branded experience. Rather than navigating to a generic platform URL, users can access their tenant through a domain that the organisation controls — for example, a subdomain of their own website or a purpose-built portal address.

What a domain represents​

A domain is a named address associated with a specific tenant. When a request arrives at the platform from a domain address, the platform uses the domain record to determine which tenant the visitor belongs to, then delivers that tenant's experience — its branding, configuration, and data — without the user needing to know anything about the underlying platform.

Each domain belongs to exactly one tenant. A tenant can have more than one domain configured, which is useful when an organisation operates several portals or serves users through multiple branded entry points.

Domain names and their relationship to the tenant domain prefix​

Every tenant has a domain prefix — a short, unique identifier that routes traffic and identifies the tenant in API paths and inbound URLs. The tenant domain prefix is always available as the default routing mechanism and cannot be removed.

A configured domain complements, rather than replaces, the domain prefix:

Routing mechanismWhere it is used
Domain prefixDefault platform routing, API paths, inbound webhooks, system-generated links
Configured domainCustom-branded portals and public-facing URLs the organisation owns and publishes

When a user arrives through a configured domain, the platform resolves the domain to its tenant and proceeds as if the user had navigated directly using the domain prefix. From that point on, all tenant isolation rules apply in the usual way.

How routing works​

When an inbound request carries a domain that the platform recognises, the lookup proceeds in two steps:

  1. The platform matches the incoming host against its registry of configured domains.
  2. The matching domain record identifies the tenant, and the request is routed into that tenant's context.

If the domain is not recognised, the request falls back to the domain prefix lookup or returns an error, depending on the entry point.

This means domain configuration is transparent to users: they simply navigate to the URL they have been given, and the platform handles the rest. There is no separate login portal for custom domains — the same authentication and session mechanisms apply regardless of which address the user arrives through.

Enabling custom-branded experiences​

Configuring a domain is a prerequisite for delivering a fully custom-branded experience. Tenants that use whitelabel or embedded portals typically register a domain for each branded surface so that users never see a generic platform address.

Combined with tenant parameters for visual configuration (such as logos, colour schemes, and support contact details), a registered domain gives the organisation full control over how the platform presents itself to end users.