Menu
Amazon API Gateway
Developer Guide

Set up Custom Domain Name for an API in API Gateway

After deploying your API, you (and your customers) can invoke the API using the default base URL of the following format:

Copy
https://api-id.execute-api.region.amazonaws.com/stage

where api-id is generated by ABP, region is specified by you when creating the API and stage is specify by you when deploying the API.

The host name portion of the URL (i.e., api-id.execute-api.region.amazonaws.com) refers to an API endpoint, which can be edge-optimized or regional. The default API endpoint can be difficult to recall and not user-friendly. To provide a simpler and more intuitive URL for your API users, you can set up a custom domain name (e.g., api.example.com) as the API's host name and choose a base path (e.g., myservice) to map the alternative URL to this API. The more user-friendly API base URL now becomes:

Copy
https://api.example.com/myservice

If you do not set any base mapping under a custom domain name, the resulting API's base URL is the same as the custom domain (e.g., https://api.example.com.) In this case, the custom domain name cannot support more than one API.

When you deploy an edge-optimized API, API Gateway sets up an Amazon CloudFront distribution and a DNS record to map the API domain name to the CloudFront distribution domain name. Requests for the API are then routed to API Gateway through the mapped CloudFront distribution.

When you create a custom domain name for an edge-optimized API, API Gateway sets up a CloudFront distribution. But you must set up a DNS record to map the custom domain name to the CloudFront distribution domain name for API requests bound for the custom domain name to be routed to API Gateway through the mapped CloudFront distribution. You must also provide a certificate for the custom domain name.

When you create a custom domain name for a regional API, API Gateway creates a regional domain name for the API. You must set up a DNS record to map the custom domain name to the regional domain name for API requests bound for the custom domain name to be routed to API Gateway through the mapped regional API endpoint. You must also provide a certificate for the custom domain name.

Note

The CloudFront distribution created by API Gateway is owned by a region-specific account affiliated with API Gateway. When tracing operations to create and update such a CloudFront distribution in CloudWatch logs, you must use this API Gateway account ID. For more information, see Log Custom Domain Name Creation in CloudTrail.

To set up an edge-optimized custom domain name or to update its certificate, you must have a permission to update CloudFront distributions. You can do so by attaching the following IAM policy statement to an IAM user, group or role in your account:

Copy
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront : updateDistribution" ], "Resource": [ "*" ] } ] }

API Gateway supports edge-optimized custom domain names by leveraging Server Name Indication (SNI) on the CloudFront distribution. For more information on using custom domain names on a CloudFront distribution, including the required certificate format and the maximum size of a certificate key length, see Using Alternate Domain Names and HTTPS in the Amazon CloudFront Developer Guide.

To set up a custom domain name as your API's host name, you, as the API owner, must provide an SSL/TLS certificate for the custom domain name.

To provide a certificate for an edge-optimized custom domain name, you can request AWS Certificate Manager (ACM) to generate a new certificate in ACM or to import into ACM one issued by a third-party certificate authority.

To provide a certificate for a regional custom domain name in a region where ACM is supported, you must request a certificate from ACM. To provide a certificate for a regional custom domain name in a region where ACM is not supported, you must import a certificate to API Gateway in that region.

To import an SSL/TLS certificate, you must provide the PEM-formatted SSL/TLS certificate body, its private key, and the certificate chain for the custom domain name. Each certificate stored in ACM is identified by its ARN. To use an AWS-managed certificate for a domain name, you simply reference its ARN.

ACM makes it straightforward to set up and use a custom domain name for an API: create in or import into ACM a certificate for the given domain name, set up the domain name in API Gateway with the ARN of the certificate provided by ACM, and map a base path under the custom domain name to a deployed stage of the API. With certificates issued by ACM, you do not have to worry about exposing any sensitive certificate details, such as the private key.

Note

API Gateway does not support self-signed SSL/TLS certificates because these certificates are not supported by CloudFront.

You must have a registered Internet domain name in order to set up custom domain names for your APIs. If needed, you can register an Internet domain using Amazon Route 53 or using a third-party domain registrar of your choice. An API's custom domain name can be the name of a subdomain or the root domain (aka, zone apex) of a registered Internet domain.

After a custom domain name is created in API Gateway, you must create or update your domain name service (DNS) provider's resource record to map the edge-optimized custom domain name to its CloudFront distribution domain name or to map the regional custom domain name to its regional API endpoint. Without such a mapping, API requests bound for the custom domain name cannot reach API Gateway.

Note

An edge-optimized custom domain name is created in a specific region and owned by a specific AWS account. Moving such a custom domain name between regions or AWS accounts involves deleting the existing CloudFront distribution and creating a new one. The process may take approximately 30 minutes before the new custom domain name becomes available. For more information, see Updating CloudFront Distributions.

This section describes how to use ACM to create an SSL/TLS certificate for a custom domain name, to set up the custom domain name for an API, to associate a specific API with a base path under the custom domain name, and to renew (aka rotate) an expiring certificate that was imported into ACM for the custom domain name.