Use cases
Custom domains

Custom domain names

API Gateway generates random domain names for our applications:


It is possible to replace those URLs by a custom domain.


This guides assume you already own the domain name you will want to use.

The first thing to do is register the domain in ACM (AWS Certificate Manager) to get an HTTPS certificate. This step is not optional.

  • Open this link (opens in a new tab) or manually go in the ACM Console and click "Request a new certificate" in the us-east-1 region (the region used for global "edge" certificates)
  • Add your domain name and click "Next"
  • Choose the domain validation of your choice.
    • domain validation will require you to add CNAME entries to your DNS configuration
    • email validation will require you to click a link you will receive in an email sent to

After validating the domain and the certificate we can now link the custom domain to our application via API Gateway.

  • Open API Gateway's "Custom Domain" configuration (opens in a new tab)

  • Switch to the region of your application

  • Click "Create"

  • Enter your domain name, select the certificate you created above and save

  • Edit the domain that was created

  • Click "Configure API mappings" to add an "API mapping": select your application and the $default stage (or dev in some cases), for example:

  • After saving the "API mappings", find the API Gateway domain name in the "Configurations" tab

  • Create a CNAME entry in your DNS to point your domain name to this domain

After waiting for the DNS change to propagate (sometimes up to several hours) your website is now accessible via your custom domain.


You can also take a look at the plugin serverless-domain-manager (opens in a new tab). It handles the custom domain creation and optionally adds the Route53 record if asked. It is still necessary to create the ACM certificate manually.

A basic implementation is proposed here : (opens in a new tab)