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.

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

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

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",
      "instructions_recipient": null,
      "instructions_email_sent_at": null,
      "upstream_uuid": "upstream_3f43d84c"
    },
    {
      "uuid": "domain_d3ba54e7",
      // ...
    },
    // ...
 "pagination": {
    "page": 7,
    "count": 322
 }
}

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

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

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",
  "instructions_recipient": null,
  "instructions_email_sent_at": null,
  "upstream_uuid": "upstream_3f43d84c"
}

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

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

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_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/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid/custom_domains/:domain_uuid

Delete a custom domain

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."
}