Custom Domains API

This API allows you to add multiple custom domains to your service.

Endpoints

How It Works

Custom domains are linked to a CloudFront distribution that routes traffic to your service. To enable secure connections, this setup requires an SSL/TLS certificate.

We group these elements — domains, CloudFront distribution, and certificate — under the concept of a Domain Certificate Group.

A Domain Certificate Group can either:

1. Use the default CloudFront distribution automatically provisioned with the service, or
2. Be associated with a new, separately created CloudFront distribution.

Once you create a domain group with domains, we initiate the setup by requesting a certificate from AWS. This process generates DNS records required to verify domain ownership, which are labeled as CERTIFICATE_DOMAIN_VERIFICATION in our API.

Once you add these DNS records, the following happens automatically:

1. AWS detects the records and issues the certificate.
2. Flightcontrol attaches both the certificate and the domains to the CloudFront distribution.
3. At this point, the domains are ready to serve traffic. If you haven’t already, you now need to update your DNS settings to point the domain to the CloudFront distribution.

The key endpoints you’ll need when first setting up the domains are:

1. Create a domain certificate group → POST /v1/services/{serviceId}/domain-certificate-groups
2. Get domains from a certificate group → GET /v1/domain-certificate-groups/{domainGroupId}/domains
   • Returns the domains and required DNS records after the group is created.
   • After adding the DNS records, use this endpoint to track domain attachment.

Walkthrough

In order to add domains to your service, you need to follow these steps:

1. Add domains to a domain certificate group - Either by creating a new domain certificate group or by adding domains to an existing one
2. Configure the domains - By verifying ownership and routing traffic

Step 1: Adding Domains to Your Service

This is where you specify which domains you want to add to your service and which CloudFront distribution to use. You have two options:

Option A: Create a new domain certificate group with domains

When creating the domain certificate group, you can also specify the domains you want to add to the group and whether to use the default CloudFront distribution or create a new one.

curl --request POST \
  --url http://api.flightcontrol.dev/v1/services/${SERVICE_ID}/domain-certificate-groups \
  --header 'authorization: Bearer ${TOKEN}' \
  --header 'content-type: application/json' \
  --data '{
  "domains": ["yourdomain.com"],
  "useDefaultCloudfront": true
}'

The useDefaultCloudfront parameter determines which CloudFront distribution to use:

• true - Uses the default CloudFront distribution automatically created with your service (recommended)
• false - Creates a new, separate CloudFront distribution

The response includes the domain certificate group ID and the IDs of the created domains:

{
  "id": "cm7xb7ocr000210k0cso2uo4d",
  "name": "Default Cloudfront",
  "status": "DRAFT",
  "isDefaultCloudfront": false,
  "cloudfrontDistributionId": null,
  "certificate": null
  "createdDomains": [
    {
      "id": "cm7xb7odb000410k0w5m3ldr5",
      "name": "yourdomain.com",
    }
  ]
}

Option B: Add domains to an existing domain certificate group

If you already have a domain certificate group and want to add more domains to it:

1. Find the domain certificate group ID

You can find the domain certificate group ID in 2 ways:

• In the UI, by going to the Details tab of the domain certificate group, which can be accessed by:

  • Opening the corresponding service card from the Environment page
  • Navigating to the Domains tab
  • Clicking on the desired domain group card

• Or via the API, by listing all the domain certificate groups for the service using the GET /v1/services/${SERVICE_ID}/domain-certificate-groups endpoint:

curl --request GET \
  --url http://api.flightcontrol.dev/v1/services/${SERVICE_ID}/domain-certificate-groups \
  --header 'authorization: Bearer ${TOKEN}'

The response will contain all the domain certificate groups for the service:

{
  "domainCertificateGroups": [
    {
      "id": "cm7xb7ocr000210k0cso2uo4d",
      "isDefaultCloudfront": true
      [...]
    }
  ]
}

2. Add your new domains to the existing group:

curl --request POST \
  --url http://api.flightcontrol.dev/v1/domain-certificate-groups/${DOMAIN_CERTIFICATE_GROUP_ID}/domains \
  --header 'authorization: Bearer ${TOKEN}' \
  --header 'content-type: application/json' \
  --data '{
  "domains": ["newdomain.com", "anotherdomain.com"]
}'

Important: After adding domains through either option, you’ll need to configure them following the steps below.

Step 2: Configuring Your Domains

After adding domains in Step 1, you need to configure them by verifying ownership and setting up traffic routing.

1. Get the domain verification records

For each domain added in Step 1, you need to verify ownership by adding the validation DNS records to your DNS provider. Those records become available when the domain status is AWAITING_VERIFICATION_RECORDS_TO_BE_SET.

So, to get the domain verification records, you’ll need to poll the GET /v1/domains/${DOMAIN_ID} endpoint until the status is AWAITING_VERIFICATION_RECORDS_TO_BE_SET.

curl --request GET \
  --url http://api.flightcontrol.dev/v1/domains/${DOMAIN_ID} \
  --header 'authorization: Bearer ${TOKEN}'

The response will contain the domain details, including the status and the DNS records:

{
  "id": "cm7xc7t380004ez2szeox61wo",
  "fcAttachmentId": "cm7xc7t3d0006ez2s5k69kf8s",
  "name": "yourdomain.com",
  "status": "AWAITING_VERIFICATION_RECORDS_TO_BE_SET",
  "type": "SUBDOMAIN",
  "lastAttachmentError": null,
  "dnsRecords": [
    {
      "status": "PENDING",
      "purpose": "CERTIFICATE_DOMAIN_VERIFICATION",
      "type": "CNAME",
      "name": "_8dd4fe5846604fbab56f7ebf0773a7bf.yourdomain.com.",
      "value": "_4ecbdb2c50d1657a2c607734066a7217.xlfgrmvvlj.acm-validations.aws.",
      "lastPropagationCheckAt": "2025-03-06T17:59:30.459Z",
      "lastPropagationCheckValue": "_4ecbdb2c50d1657a2c607734066a7217.xlfgrmvvlj.acm-validations.aws",
      "lastPropagationCheckError": {}
    },
    {
      "status": "PENDING",
      "purpose": "SERVICE_CONNECTION",
      "type": "CNAME",
      "name": "yourdomain.com",
      "value": "d2qmzbf7cn1k25.cloudfront.net",
      "lastPropagationCheckAt": null,
      "lastPropagationCheckValue": null,
      "lastPropagationCheckError": null
    }
  ]
}

Once AWAITING_VERIFICATION_RECORDS_TO_BE_SET is reached, look for records with the purpose field set to CERTIFICATE_DOMAIN_VERIFICATION. These are the records you need to add to your DNS provider to verify domain ownership.

2. Add verification records and monitor status

Add the verification records to your DNS provider. Then, continue polling the same endpoint to monitor the domain status:

curl --request GET \
  --url http://api.flightcontrol.dev/v1/domains/${DOMAIN_ID} \
  --header 'authorization: Bearer ${TOKEN}'

The process will progress through these stages:

1. AWS detects your DNS records and issues the SSL certificate
2. Flightcontrol attaches the certificate and domains to the CloudFront distribution
3. The domain status changes to ATTACHED when complete

If there’s an error during any part of this process, the status will change to ERROR_ATTACHING with details in the lastAttachmentError field.

3. Route traffic to your service

Once the domain status is ATTACHED, your domain is ready to serve traffic. The final step is to add the SERVICE_CONNECTION DNS records to your provider:

1. Get the SERVICE_CONNECTION records from the domain response
2. Add these records to your DNS provider
3. Wait for DNS propagation (can take up to 24-48 hours depending on your provider)

After DNS propagation completes, your domain will be fully operational and routing traffic to your service.

Error Handling

If there’s an error during the domain attachment process, you can retry the attachment using the POST /v1/domain-certificate-groups/{domainGroupId}/retry-attachment endpoint.

curl --request POST \
  --url http://api.flightcontrol.dev/v1/domain-certificate-groups/${DOMAIN_CERTIFICATE_GROUP_ID}/retry-attachment \
  --header 'authorization: Bearer ${TOKEN}'

This will retry the attachment of the domains to the domain group.

Common Errors

Aws:ACM:Error:VALIDATION_TIMEOUT

This error occurs when the ACM certificate validation process times out. This is caused if the user takes more than 72h to verify the domain ownership.

Aws:ACM:Error:NUMBER_OF_DOMAINS_EXCEEDS_LIMIT

This error occurs when the number of domains in the domain group exceeds the ACM quota limit. Default limit is 10.

You can either remove domains, ask AWS for a quota increase for ‘Number of domain names per ACM certificate’ or add the domains in a new domain group.

See AWS ACM Quotas for more information.