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