Custom domains

On this page, we'll dive into the different custom domains endpoints you can use to manage custom domains programmatically. We'll look at how to query, create, update, and delete custom domains.

The custom domain model

The custom domain model contains all the information about your custom domains.

Properties

Name
uuid
Type
string
Description
Unique identifier for the custom domain.
Name
host
Type
string
Description
The host of the custom domain. This is where your customer wants to access your application. This is the domain where your user will have to add a CNAME record.
Name
prepend_path
Type
string
Description
An optional path prefix that will be added to all requests forwarded to your upstream. For example, if set to /sites/client1, a request to app.company.com/about will be forwarded to your upstream as /sites/client1/about. It can only contain letters, numbers, dashes, and underscores.
Name
challenge_type
Type
string
Description
The type of challenge used to validate the certificate. It can be one of the following values: http01, dns01. Default value is http01. http01 challenge will issue certificates on demand and dns01 challenge will issue certificates when the _acme-challenge DNS records are found.
The dns01 challenge is useful if you want to use SaaS Custom Domains Shield, our product that puts Cloudflare DDoS protection and WAF in front of your custom domains.
Name
redirect_to_www
Type
boolean
Description
Indicates whether the custom domain should redirect to the www subdomain. This is useful if you want to redirect all traffic to the www subdomain. Default value is false.
Name
status
Type
string
Description
The status of domain's proxy DNS records. This is the DNS record that points the custom domain to SaaS Custom Domains' proxy fleets. It can be one of the following values: pending_check, dns_records_found, dns_records_not_found, and dns_check_unnecessary.
Name
tls_certificate_issued
Type
boolean
Description
Indicates whether a TLS certificate has been issued for the custom domain.
Name
acme_challenge_dns_record_status
Type
string
Description
The status of the ACME challenge DNS record. It can be one of the following values: valid, pending, not_found. This property is only used for custom domains with the dns01 certificate challenge type.
Name
delegated_domain_control_validation_record_hostname
Type
string
Description
The hostname of the ACME challenge DNS record. This property is only used for custom domains with the dns01 certificate challenge type.
Name
delegated_domain_control_validation_record_value
Type
string
Description
The value of the ACME challenge DNS record. This property is only used for custom domains with the dns01 certificate challenge type.
Name
instructions_email_sent_at
Type
timestamp
Description
The timestamp when the instructions email was sent to the user. Only applies if you decided to send the instruction email to the user when you created the custom domain.
Name
instructions_recipient
Type
timestamp
Description
The email address of the user who was sent the instructions email. Only applies if you decided to send the instruction email to the user when you created the custom domain.
Name
last_dns_check_at
Type
timestamp
Description
The timestamp when the last DNS check was performed.
Name
created_at
Type
timestamp
Description
The date and time when the custom domain was created.
Name
updated_at
Type
timestamp
Description
The date and time when the custom domain was last updated.

GET

/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains

Retrieve all

This endpoint allows you to retrieve a paginated list of all custom domains belonging to an upstream. By default, 20 custom domains are shown per page.

Optional attributes

Name
host
Type
string
Description
Find custom domain with the given host.
Name
page
Type
integer
Description
The page number to retrieve. Default value is 1.
Name
per_page
Type
integer
Description
The number of items to retrieve per page. Default value is 20.

Request

GET

/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains

curl -G https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains \
  -H "Authorization: Bearer {token}" \
  -d page=7

Response

{
  "data": [
    {
      "uuid": "domain_52069e63",
      "host": "app.user.com",
      "prepend_path": null,
      "created_at": "2022-11-14T13:19:42.193+01:00",
      "updated_at": "2023-03-11T08:32:27.239+01:00",
      "last_dns_check_at": "2023-03-11T08:32:27.216+01:00",
      "status": "dns_records_found",
      "tls_certificate_issued": true,
      "acme_challenge_dns_record_status": "valid",
      "challenge_type": "http01",
      "redirect_to_www": false,
      "instructions_recipient": null,
      "instructions_email_sent_at": null,
      "upstream_uuid": "upstream_3f43d84c",
      "delegated_domain_control_validation_record_hostname": null,
      "delegated_domain_control_validation_record_value": null
    },
    {
      "uuid": "domain_d3ba54e7",
      // ...
    },
    // ...
 "pagination": {
    "page": 7,
    "count": 322
 }
}

POST

/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains

Create

This endpoint allows you to add a new custom domain to an upstream.

Required attributes

Name
host
Type
string
Description
The host of the custom domain. This is the domain where your user wants to access your application. Your user will have to add a CNAME record to this domain pointing it to in.saascustomdomains.com.

Optional attributes

Name
instructions_recipient
Type
string
Description
The email address where the instructions to add the CNAME record will be sent. You need to have a valid and confirmed Sender Signature in your SaaS Custom Domain account in order to use this.
Name
prepend_path
Type
string
Description
An optional path prefix that will be added to all requests forwarded to your upstream. For example, if set to /sites/client1, a request to app.company.com/about will be forwarded to your upstream as /sites/client1/about. It can only contain letters, numbers, dashes, and underscores.
Name
challenge_type
Type
string
Description
The challenge type for domain control verification. Possible values are http01 and dns01. If not provided, the default value is http01.
Name
redirect_to_www
Type
boolean
Description
Indicates whether the custom domain should redirect to the www subdomain. This is useful if you want to redirect all traffic to the www subdomain. Default value is false.

Request

POST

/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains

curl https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains \
  -H "Authorization: Bearer {token}" \
  -d host="app.user.com"

Response

{
  "uuid": "domain_4e30e873",
  "host": "app.user.com",
  "prepend_path": null,
  "created_at": "2023-03-11T15:38:12.550+01:00",
  "updated_at": "2023-03-11T15:38:12.550+01:00",
  "last_dns_check_at": null,
  "status": "pending_check",
  "tls_certificate_issued": false,
  "acme_challenge_dns_record_status": "valid",
  "challenge_type": "http01",
  "redirect_to_www": false,
  "instructions_recipient": null,
  "instructions_email_sent_at": null,
  "upstream_uuid": "upstream_3f43d84c",
  "delegated_domain_control_validation_record_hostname": null,
  "delegated_domain_control_validation_record_value": null
}

GET

/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:domain_uuid

Retrieve

This endpoint allows you to retrieve a custom domain by providing its UUID. Refer to the list at the top of this page to see which properties are included with custom domain objects.

Request

GET

/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:domain_uuid

curl https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:domain_uuid \
      -H "Authorization: Bearer {token}"

Response

{
  "uuid": "domain_3cdfe9a4",
  "host": "*.app.com",
  "prepend_path": null,
  "created_at": "2023-03-11T15:38:12.550+01:00",
  "updated_at": "2023-03-11T15:43:16.672+01:00",
  "last_dns_check_at": "2023-03-11T15:43:16.667+01:00",
  "status": "dns_check_unnecessary",
  "tls_certificate_issued": false,
  "acme_challenge_dns_record_status": "pending",
  "challenge_type": "dns01",
  "redirect_to_www": false,
  "instructions_recipient": null,
  "instructions_email_sent_at": null,
  "upstream_uuid": "upstream_3f43d84c",
  "delegated_domain_control_validation_record_hostname": "_acme-challenge.testhost.app.com",
  "delegated_domain_control_validation_record_value": "_acme-challenge.testhost.app.com.challenges.saascustomdomains.com"
}

DELETE

/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:domain_uuid

Delete

This endpoint allows you to delete custom domains.

Request

DELETE

/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:domain_uuid

curl -X DELETE https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:domain_uuid \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Custom domain domain_4e30e873 (app.user.com) deleted."
}

POST

/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:domain_uuid/verify_dns_records

Verify DNS records

This endpoint allows you verify DNS records for a custom domain.

Once the domain has been created, SaaS Custom Domains automatically checks for the presence of the required DNS records.

We check the DNS records immediately, and then in 1, 2, 3, 5, 10, 15, 30, and 60 minutes.

For example, if you create your domain at 9:00, we'd run the checks at the following times: 9:00, 9:01, 9:02, 9:03, 9:05, 9:10, 9:15, 9:30, and 10:00

After that, we check DNS records once every 3 hours. If you need to trigger the check manually or just check if the DNS records are valid, you can use this endpoint.

Response

Returns the host of the custom domain and the status of the DNS records. Status can be one of the following values: valid, pending, and invalid.

If the status is valid, it means we found the required DNS records and the custom domain is ready to be used.

If the status is pending, it means we haven't finished checking the DNS records yet. If the status is invalid, it means we couldn't find the required DNS records and we'll check again later.

Request

POST

/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:domain_uuid/verify_dns_records

curl -X POST https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:domain_uuid/verify_dns_records \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "DNS records verification complete.",
  "dns_status": "valid",
  "host": "app.example.com"
}