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
, anddns_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 thedns01
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 ishttp01
.http01
challenge will issue certificates on demand anddns01
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.
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
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
}
}
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
anddns01
. If not provided, the default value ishttp01
. Only wildcard domains can have thechallenge_type
set todns01
.
Request
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
}
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
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
This endpoint allows you to delete custom domains.
Request
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."
}
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
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."
}