Skip to main content

Custom Domain Names


If you are following our cookiecutter pattern, then you are using Lambda's free Function URLs. Using a custom domain name with FURLs is as easy as adding CloudFront. FURLs also work out of the box with JavaScript & Assets.

For API Gateway, custom domain names are the only way to get JavaScript & Assets working correctly. The instructions below are simple ClickOps process for setting these up. First, no matter which web integration you are using, you will need to support SSL traffic with a custom certificate.

Secure Certificate with ACM

We are going to use AWS Certificate Manager to secure your HTTPS traffic under your custom domain. Again, this assumes your domain is setup in Route53 since you will need to validate the certificate and AWS makes that super easy with DNS.

  • AWS Console -> Certificate Manager
  • Click "Request a certificate" button.
  • Select "Request a public certificate", and "Request a certificate" button.
  • Domain name. Ex: *
  • Click "Next"
  • Select "DNS validation", and "Review".
  • Click "Confirm and request" button.
  • Click the tiny disclosure triangle beside your domain name.
  • Click the "Create record in Route 53" button then "Create" again in modal.
  • Click "Continue"

Verification will take about 3 minutes. From the Certificate Manager dashboard, you can wait and/or hit the 🔄 button and the Status will change from "Pending validation" to "Issued".

API Gateway Custom Domain Names

No matter if you have HTTP API, REST API Public, or REST API Private with an ALB; you will need to specify a Custom Domain Name in API Gateway. The only exception would be if you are using an Application Load Balancer without REST API. Here are the ClickOps steps to setup an API Gateway Custom Domain Name:

  • AWS Console -> API Gateway
  • Click "Custom domain names" in the left panel.
  • Click "Create" button
  • Enter domain name. Ex:
  • Use default TLS 1.2 (recommended).
  • Endpoint type Regional.
  • ACM certificate. Select wildcard matching domain from above.
  • Click "Create domain name"

After this has been created, the mappings tab should be selected. From here we need to create an API Mapping to point to your specific API Gateway and stage/path. Assuming it is selected:

  • Click the "API mappings" tab.
  • You should see "No API mappings have been configured..." message
  • Click "Configure API mappings" button.
  • Click "Add new mapping" button.
  • Select your API: Ex: myapp-main (HTTP - 511n0spvi9).
  • Select your Stage: Ex: staging.
    • If you see Stage and staging ignore Stage. Known REST bug.
  • Leave Path empty.
  • Click the "Save" button.

From here there are various ways to setup Route53 and route traffic to your Lambda application. This work simply sets up API Gateway to understand how traffic is routed via what is called SNI. Choose one of the methods below matching your need for Route53.

Route53 for API Gateway

✅ Make sure to complete the "API Gateway Custom Domain Names" section first.

From here all we need is a simple DNS entry in Route53 that points to the "API Gateway domain name" we created in the step above. That domain name looks something like:

  • AWS Console -> Route 53 -> Hosted zones
  • Click on your domain
  • Click "Create record"
  • Click "Switch to wizard" if not selected already.
  • Select "Simple routing"
  • Click "Next"
  • Click "Define simple record"
  • Record name. Ex: myapp
  • Record type: A - Routes traffic to an IPv4 address and some AWS resources
  • Value/Route traffic to: Alias to API Gateway API
  • Choose Region: Ex: us-east-1
  • Choose endpoint: Should autofill, Ex:
  • Evaluate target health: No
  • Click "Define simple record"
  • Click "Create records"

Simple CloudFront Distribution

Baisc reference steps for creating a CloudFront distribution. If you are using FURLs, then your "origin Domain Name" would end with something like If you are using API Gateway, it would be the API Gateway's custom domain and would look like this The final CloudFront distribution name ( would be the Route53 target instead. Here are the steps to create your CloudFront Distribution:

  • AWS Console -> CloudFront -> Create Distribution -> Web -> Get Started
  • Origin Domain Name:
  • Origin Path: /production (not needed for FURLs)
  • Minimum Origin SSL Protocol: TLSv1.2
  • Origin Protocol Policy: HTTPS Only
  • Origin Custom Headers: X-Forwarded-Host (⚠️ IMPORTANT)
  • Viewer Protocol Policy: Redirect HTTP to HTTPS
  • Cached HTTP Methods: OPTIONS
  • Cache Based on Selected Request Headers: Whitelist - Accept (⚠️ Allows respond_to to work)
  • Object Caching: Use Origin Cache Headers
  • Forward Cookies: All
  • Query String Forwarding and Caching: Forward all, cached based on all
  • Compress Objects Automatically: Yes
  • Alternate Domain Names (CNAMEs):
  • SSL Certificate: Custom SSL Certificate (select * from step above)

This process takes a while to fully deploy. Once done you will have a CloudFront domain name looking something like Head to Route53 and create an alias for to this CloudFront distibution domain name.