Hosted custom domains

A custom domain serves your hosted pages on your own subdomain, for example calcs.example.com, so visitors never see the Aztec-Calcs address.

Before you start

• A subdomain you control, such as calcs.example.com. A bare domain such as example.com doesn't work.
• Access to its DNS records.
• A customer admin adds the domain in the portal under Custom domain. The portal then shows the exact DNS records to create.

A hostname must be valid, have no wildcard, scheme, path or port, and use ASCII letters only (no internationalized names). It can be up to 233 characters. It can't be an Aztec-Calcs domain.

Minimal example

1. In the portal, add calcs.example.com.

2. Create the two DNS records the portal shows:

   Type	Name	Value
   CNAME	calcs.example.com	The target the portal shows
   TXT	_aztec-calcs-verify.calcs.example.com	The value the portal shows

3. Wait for the status to change to Active. Then open https://calcs.example.com/auto-loan-payment in a browser.

Options

On a custom domain, the hostname stands for your cobrand, so addresses are short:

Address	Page
/	The index page
/{calculatorKey}	A calculator page
?locale=	The page language
Any other path	Your branded "not found" page

Vanity URL slugs don't apply on a custom domain. Calculator pages on the Aztec-Calcs address carry a rel="canonical" link to your custom domain. A serving custom domain is also allowed to use the embed endpoints without an entry in your allowed domains.

The domain goes through these statuses:

Status	Meaning
Pending DNS	The platform is waiting for your records. It checks every minute for 30 minutes, then every 15 minutes.
Issuing certificate	The records are correct, and the certificate is on its way. The platform checks every minute.
Active	The domain serves pages. The platform re-checks daily.
Action needed	A record changed or broke. The domain keeps serving. The platform re-checks every 15 minutes.
Failed	The domain didn't complete setup. A domain that stays in Pending DNS, Issuing certificate or Action needed for 7 days fails.
Removed	You removed the domain.

Errors and limits

Only Active and Action needed domains serve pages. For any other hostname, visitors see the plain page "This site isn't configured". The page is the same whether the hostname is unknown, not finished or removed.

When you add a hostname, the portal rejects it with one of these codes:

Code	Cause
invalid_hostname	The name isn't a valid hostname, or it's too long.
apex_domain	The name is a bare domain. Use a subdomain.
platform_domain	The name is an Aztec-Calcs domain or a subdomain of one.
wildcard_not_allowed	The name has a *.
idn_not_supported	The name has non-ASCII characters.

Limit	Value
Hostname length	233 characters
DNS label length	63 characters
Check now	A manual check can run once every 30 seconds.
Changes	A new, changed or removed domain shows on the hosted site within about a minute.
Error pages	The hosted site can't send a 404 or 503 status. Error pages come with a 200 status.

Related API reference

Custom-domain pages load their data from the embed endpoints. See Embed endpoints and allowed domains.

• Calculate
• Get calculator schema