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
status
Type
string
Description
The status of the custom domain when it comes to its DNS records. It can be one of the following values: pending_check, dns_records_found, dns_records_not_found, and dns_check_unnecessary.
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.

Wildcard domains

Following properties are only used with wildcard domains and can be disregarded for non-wildcard domains.

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 wildcard custom domains with the dns01 certificate challenge type.
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. This property is only used for wildcard custom domains. 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.
Name
delegated_domain_control_validation_record_hostname
Type
string
Description
The hostname of the ACME challenge DNS record. This property is only used for wildcard 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 wildcard custom domains with the dns01 certificate challenge type.

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",
      "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",
      "acme_challenge_dns_record_status": "valid",
      "challenge_type": "http01",
      "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
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. Only wildcard domains can have the challenge_type set to dns01.

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",
  "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",
  "acme_challenge_dns_record_status": "valid",
  "challenge_type": "http01",
  "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",
  "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",
  "acme_challenge_dns_record_status": "pending",
  "challenge_type": "dns01",
  "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 to trigger DNS records verification 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 24 hours. If you need to trigger the check manually, you can use this endpoint.

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 will be verified shortly."
}