Skip to main content

Subordinate Domains

Nebula series and beyond

Subordinate domains are available on the Nebula series and later.

Subordinate domains are a convenience feature that lets the platform synthesise all endpoint FQDNs for a brand automatically, so you do not need to register and delegate a separate domain for each brand or hand-author individual FQDN entries.

How it works​

You provide two things:

  1. A base domain: a single registered domain that you delegate to the HaaS platform as a Biza Managed Zone (e.g. cdr.holder.com.au).
  2. A brand slug per brand: a short identifier for each brand (e.g. firstbank, firstbankbusiness).

The platform then derives every endpoint FQDN as:

<endpoint>.<brandSlug>.<baseDomain>

Example​

Brand slugBase domainDerived auth endpointDerived API endpoint
firstbankcdr.holder.com.auauth.firstbank.cdr.holder.com.auapi.firstbank.cdr.holder.com.au
firstbankbizcdr.holder.com.auauth.firstbankbiz.cdr.holder.com.auapi.firstbankbiz.cdr.holder.com.au

All subordinate brands share the same base domain and delegation. You need only one DNS delegation, for the base domain, regardless of how many subordinate brands your space has.

  • Brand slugs must be unique within the space, and match [a-z0-9], 1–32 characters (lowercase letters and digits only).

Why use it​

Without subordinate domains, every brand needs its own registered domain, and each of those domains needs its own DNS delegation runsheet completed. Subordinate domains remove that per-brand DNS onboarding step entirely:

  • One delegation covers every subordinate brand, present and future. The base domain is delegated once, out-of-band. Adding a new whitelabel brand later requires zero DNS work. You simply add the brand with a new slug and it resolves under the already-delegated base.
  • Custom-domain brands still need their own delegation. A brand that supplies its own registered domain is delegated exactly as before.

For example, a space with one custom-domain brand and three subordinate brands needs two delegations in total: one for the custom domain, one for the shared base β€” not four.

HaaS Manager​

HaaS Manager is a single, space-level administration console. There is only ever one per space, and it is only ever served on the primary brand's domain path. Where exactly that is depends on whether subordinate domains are configured:

Space shapeHaaS Manager hostname
No subordinate domains (every brand has its own custom domain)haas-manager.<primary brand's domain>
All brands are subordinatehaas-manager.<baseDomain>
Mixed β€” primary has its own custom domain, one or more secondary brands are subordinatehaas-manager.<baseDomain>

In other words: as soon as a base domain is configured for the space, HaaS Manager is served from that base domain, even if the primary brand has its own custom domain. This is by design as it lets HaaS Manager live at a stable, predictable location independent of which brand happens to be primary.

This is mainly a consideration for new spaces being configured with subordinate domains from the outset. Adding a base domain to an existing space that already has HaaS Manager live on the primary brand's domain will move the HaaS Manager URL. Update any bookmarks, IdP/SSO redirect URIs and allowlists that reference it before making the change.

Requirements​

  • DNS mode must be Biza Managed Zone. The platform needs to control the DNS zone for the base domain so it can DNS-validate certificates for the synthesised hostnames automatically. Subordinate domains cannot be used with Customer Managed Zone or No Custom Domain.
  • Subordinate domains and hand-authored custom domains can be mixed within the same space. Each brand independently chooses whether to supply its own domain or take a subordinate domain under the shared base.

Certificates​

Public certificates for subordinate brands' endpoints are requested and renewed automatically via Amazon Certificate Manager, DNS-validated against the base domain zone. There is no customer action required.

The exception is the CDR secure endpoints (secure-auth, api): these use certificates issued by the ACCC, and the ACCC issues an individual certificate per brand, including subordinate brands, which is never wildcarded. Onboarding a subordinate brand into the CDR ecosystem still requires the usual per-brand ACCC certificate process; see Per Brand: ACCC Production CDR and the annual renewal runsheet.

DNS delegation​

Delegate the base domain to the HaaS platform following the standard Domain Delegation runsheet. You only need to delegate the base domain once; all subordinate brand FQDNs are managed automatically within that zone.