Custom domains

Unless you're running an application for personal use, you'll probably want to swap out the default API gateway URL with a custom domain.This is easy to do in two steps:

  1. Get a free SSL/TLS certificate from Amazon through the AWS Certificate Manager (ACM)
  2. Add the certificate ARN to your Zappa settings file and certify.

Getting an SSL certificate

If you've already obtained a certificate from ACM for the domain you want to use with your Zappa application, you can skip this section.

  • Your first step is to visit the ACM Console. To avoid issues you'll want to make sure you're in the N. Virginia region (us-east-1).
  • There will be a button to 'Request a Certificate' or 'Provision Certificates' depending on whether you've already created any certificates in the region or not.
  • Choose to request a public certificate.
  • Add your domain name. You can use an asterisk as a wildcard (eg *
  • Select how you want to validate ownership of your site. The easiest way is to choose DNS validation and then continue. As long as you use Amazon nameservers, if you click the domain that's pending validation it will give you a button that says "Create record in Route 53".
  • That's it! Now all you have to do is wait for validation — it will tell you that validation can take a while, but with DNS verification I've never seen it take longer than a couple minutes.

Once you're back on the main ACM page, expand the domain you just provisioned and look for the section that lists the ARN. Copy the ARN, since that's what we'll use in the next section to tell Zappa about the certificate.

Using your SSL certificate with Zappa

Now that you have the ARN of the SSL certificate that you want to use with your Flask site, you'll need to add the ARN and domain name to your Zappa settings file. Here's our example settings file as a reminder:

    "dev": {
        "app_function": "",
        "aws_region": "us-east-1",
        "profile_name": "default",
        "project_name": "zappaapp",
        "runtime": "python3.6",
        "s3_bucket": "[enter dev bucket name here]"
    "production": {
        "app_function": "",
        "aws_region": "us-east-1",
        "profile_name": "default",
        "project_name": "zappaapp",
        "runtime": "python3.6",
        "s3_bucket": "[enter prod bucket name here]",
        "certificate_arn": "[enter arn here]",
        "domain": "[enter custom domain here]"

Add your ARN to the certificate_arn element, and add the domain that you set up the certificate for to the domain element. In the settings file above we only have a custom domain set up for the production stage, but if you want a separate domain set up for the dev stage then all you have to do is add a new certificate_arn and domain to that section of the file.

After saving your updated settings file, all you need to do is run

zappa certify production

which will point the AWS API gateway at your custom domain instead of the default Zappa URL. When certify is run Zappa will notify you that it can take 40 minutes or so for the domain to be propagated through AWS, but the average time is much less than that. After running certify you can run zappa deploy production and your application will be invoked by requests to the new domain!

If you're finding this guide useful, you may want to sign up to receive more of my writing at