Custom domain in AWS API Gateway

A step by step guide to set up a custom domain in Amazon Web Services API Gateway.

Maciej Treder
May 21, 2018 · 6 min read

Serverless environment is getting more popular from day to day. FaaS (Function as a Service) gives you an ability to publish your app in small independent pieces and chain them up together into scalable microservices architecture. Today I would like to cover the process of using the custom domain (let’s say in the AWS API Gateway.

The flow

What happens when a user requests a webpage? How it comes to the AWS? Take a look at high-overview flow-chart:

  1. User requests the web-page/API by URL; Request comes to the DNS server
  2. DNS server resolves CNAME and A field in the last CNAME chain element
  3. The request comes to the AWS CloudFront (CNAME resolved by DNS), AWS passes it to the API Gateway
  4. API Gateway looks for a connection between the Host header and declared APIs, passes the request to the Lambda and responds to the browser
  5. The user receives the response (i.e. HTML code, which can be rendered by the browser)


When the user is typing the domain address in their browser, in fact, they are addressing there request to the specific origin, with the unique IP address. How is it achieved? First of all, users request goes to the DNS server, which is mapping domain names to the IPs. That’s the high overview. In fact, DNS server is doing much more, i.e. it is resolving CNAMEs. CNAME is a special kind of redirection. You can think about it as a 30x HTTP redirection, with one difference: user doesn’t see that this redirect occurs. Imagine that DNS server is a postman, and the user request is a letter. Postman is taking a look at the letter and sees the address line (Park Lane ave 123), then he is looking into a notebook and sees annotation “All letters to Park Lane ave 123, should be delivered to Forest ave 321”. That is what postman does. He doesn’t need to inform the sender about that the address has changed, the only important thing is to deliver the dispatch.

This is an important concept which we are going to use later.

Let’s start configuration!

Issue a certificate

So you have your domain registered within some registrar (it doesn’t need to be AWS, i.e. is registered within OVH). What we need to do now, is issue an SSL certificate from Amazon. It is necessary to route traffic to the AWS and don’t get that traffic rejected by Amazon.

Login to AWS console and navigate to “Certificate Manager”. Make sure you set the region to US East — North Virginia! That’s really important. It doesn’t matter in which region you want to deploy your API. SSL certificates must be issued in the US East (North Virginia) region. Now click on “Request a certificate” button:

In the next view, choose “Request a public certificate” and confirm your selection by clicking on “Request certificate” button.

Now you need to choose domain names for which you want to issue a certificate. Keep in mind that and are two different domains. The other important thing is, that a wildcard (*) matches only one “section” (from a dot . to dot .). So, if I want to issue the certificate which will work with following URLs:

My settings are:

After clicking “next”, you will need to choose validation method. Amazon needs to makes sure, that you are the owner of the domain for which you are requesting the certificate. There are two ways for that. First one is manipulation of DNS entries, the second one is an e-mail validation. I prefer the second one:

What Amazon will do now, it will look up at DNS registry and send an e-mail with the activation link to the e-mail addresses listed in the “Registrant Contact”, “Admin contact” and “Tech Contact”. You can check your domain whois information on the ICANN whois page.

Ok. Now we are ready to click on the “Review” button, and then, finally “Confirm and Request”:

At the next page, you will get some information that your Certificate is requested and that the verification e-mail has been sent. After a while you should get it:

Click on the link in the message and “approve your certificate”:

Finally! We have it:

Setup custom domain on your API

Now you can Navigate to the API Gateway (remember to change region to this one where your API is located).

I assume that you have your API set up, and you have the “maintenace link” (i.e., If not check out my article How to Deploy JavaScript & Node.js Applications to AWS Lambda for Twillio. You can also (if you have some Angular application) take a look at @ng-toolkit/serverless library for Angular app (An article about usage of this plugin can be found here: Angular & Serverless)

Now in the left-side menu choose "Custom Domain Names" link and click on "Create Custom Domain Name" button. New, blank custom domain name form should appear on your screen:

Fill up the form, and remember: and are two different domains, so you need to customize them separately (both of them can point to the same lambda — no problem). Choose the certificate which you created in the previous step, add mapping to your lambda application, and choose the stage which you want to use:

After adding your custom domains, you should see the “Target Domain Name”, set up in CloudFront (AWS is doing that automatically). Do you remember section about CNAME? We are going to use that target domain in the CNAME field of your domain entry in the DNS. This is how the configuration of my domain looks like:

You’re done! Now you need only to wait for DNS data propagation across the web! You can check if the data is propagated already using whatsmydns tool.

Thanks for reading!

Maciej Treder,

Follow me on Twitter and GitHub to be notified about my new activites.

If you want, you can donate my activity on OpenCollective, DonorBox or LiberaPay.

Maciej Treder

Written by

Senior Software engineer at Akamai Tech; Twilio Champion; Author of ng-toolkit project Enthusiast of Angular

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade