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
- 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.
List all custom domains for an upstream
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",
"instructions_recipient": null,
"instructions_email_sent_at": null,
"upstream_uuid": "upstream_3f43d84c"
},
{
"uuid": "domain_d3ba54e7",
// ...
},
// ...
"pagination": {
"page": 7,
"count": 322
}
}
Create a custom domain
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
.
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",
"instructions_recipient": null,
"instructions_email_sent_at": null,
"upstream_uuid": "upstream_3f43d84c"
}
Retrieve a custom domain
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_4e30e873",
"host": "app.user.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_records_not_found",
"instructions_recipient": null,
"instructions_email_sent_at": null,
"upstream_uuid": "upstream_3f43d84c"
}
Delete a custom domain
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."
}