Custom domain types

Domain types

To use SaaS Custom Domains effectively, you need to know about 3 different types of custom domains supported at SaaS Custom Domains: subdomains, apex domains, and wildcard domains.

Subdomains

A subdomain is a part of a larger domain. It's a way to organize and navigate the hierarchy of a website, and it typically reflects specific content or functions of the site.

For example, in the domain blog.example.com, blog is the subdomain of the main domain example.com. Subdomains can be used to separate different areas of a website, such as a blog, shop, or support section. They are helpful in organizing content and can be managed separately, allowing for different hosting, security settings, or even branding.

How to add a custom subdomain?

Suppose you want to create a custom subdomain like custom-subdomain.example.com.

1. Select the Upstream: Choose the upstream for which you wish to create a custom domain.
2. Create the Custom Domain: Navigate to the dashboard and create the custom domain.
3. Configure a CNAME Record: Create a CNAME record at custom-subdomain.example.com that points to in.saascustomdomains.com.
4. Verify and Access: That's it! You're all set. Visit custom-subdomain.example.com, and you should see your app.

Apex Domains

An apex domain, also known as a root domain or naked domain, is the primary address of a site without any subdomains or prefixes. It's the core domain name that users type into their browser to access a website.

For example, example.com is an apex domain. It's the fundamental, top-level domain that doesn't include www or any other subdomains.

How to add a custom apex domain?

Suppose you want to create a custom apex domain like example.com.

1. Select the Upstream: Choose the upstream for which you wish to create a custom domain.
2. Create the Custom Domain: Navigate to the dashboard and create the custom domain.
3. Configure A Records: Create two A records at example.com that point to 99.83.186.151 and 75.2.96.173. Both are required, because we use two IP addresses for high availability. A domain with one wrong IP can still load, but it won't verify.
4. Verify and Access: That's it! You're all set. Visit example.com, and you should see your app.

Don't add AAAA (IPv6) records for the domain, and remove any old A or AAAA records that point elsewhere. We don't offer IPv6 addresses, and stray records stop certificates from being issued.

If you create the domain with redirect_to_www turned on, also create a CNAME record at www.example.com that points to in.saascustomdomains.com.

Wildcard Domains

Wildcard domains are used to match requests for non-existent subdomains. They are specified by using an asterisk * as part of the domain name, usually at the subdomain level.

A wildcard domain might look like *.example.com, and it will match requests for any subdomain that hasn't been specifically defined within example.com. This is useful in scenarios where you want to dynamically generate subdomains or have a catch-all routing for various subdomains.

For example, you might use wildcard domains to create personalized URLs for users, like john.example.com or sarah.example.com, without having to create a custom domain and DNS record for each user. You'd set up the wildcard domain once, as shown below, and then handle the routing within your application.

Another use-case for wildcard domains is that they can be used to create a catch-all routing for subdomains. For example, you might want to redirect all requests for non-existent subdomains to a specific page or URL. You can do this by creating a wildcard domain and then handling the routing within your application.

A wildcard matches one level of subdomains: *.example.com covers john.example.com but not a.b.example.com. Wildcards on public suffixes, such as *.co.uk, are rejected.

How to add a custom wildcard domain?

Wildcard domains must use the DNS-01 challenge and get a single wildcard certificate for *.example.com that covers every subdomain. The API rejects a wildcard domain with the http01 challenge type ("Wildcard domains must use DNS-01 challenge"), and the dashboard disables that option for wildcard hosts.

Suppose you want to create a custom wildcard domain like *.example.com.

1. Choose the upstream for which you wish to create a custom wildcard domain.
2. Create the custom domain *.example.com with the DNS-01 challenge type ("challenge_type": "dns01" in the API).
3. Create a CNAME record at *.example.com that points to in.saascustomdomains.com. If you can't add a wildcard record, create a CNAME record for each subdomain instead, e.g. john.example.com and sarah.example.com, pointing to in.saascustomdomains.com.
4. Create a CNAME record at _acme-challenge.example.com that points to _acme-challenge.example.com.challenges.saascustomdomains.com. This record lets the certificate authority verify that you own the domain. Keep it in place and set to DNS only (not proxied), because it's needed for every certificate renewal.
5. Visit john.example.com or sarah.example.com, and you should see your app, served with the certificate for *.example.com.

Use your own CNAME target

Your customers can point their CNAME records at a hostname on your domain, such as in.yourapp.com, that is itself a CNAME to in.saascustomdomains.com. Add it under Account settings » Custom CNAMEs so the DNS instruction emails show it instead of in.saascustomdomains.com. This feature is enabled on request; contact support to turn it on.

Troubleshooting

If a domain doesn't verify or its certificate isn't issued, see the help center for common causes and fixes.