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 asexample.comdoesn'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
-
In the portal, add
calcs.example.com. -
Create the two DNS records the portal shows:
Type Name Value CNAMEcalcs.example.comThe target the portal shows TXT_aztec-calcs-verify.calcs.example.comThe value the portal shows -
Wait for the status to change to Active. Then open
https://calcs.example.com/auto-loan-paymentin 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.