Use Custom Domain Name as API Gateway API Host Name
After deploying your API, you (and your customers) can invoke the API using the default root URL of the following format:
Here, the host name of the URL (i.e.,
can be difficult to recall and not user-friendly. To provide a simpler and more intuitive URL for your API users,
you can use API Gateway to 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 present an alternative URL of the API of the following format:
The base path can be an empty string. In this case, the API's root URL
is the same as the custom domain (e.g.,
https://api.example.com.) In this case,
the custom domain name can support only one API.
For every API you create, API Gateway sets up an Amazon CloudFront distribution for the API. Requests with the default API URL are routed through the corresponding CloudFront distribution. Similarly, for every custom domain name, API Gateway sets up a CloudFront distribution. An API request with the custom domain name is routed through the custom domain name's CloudFront distribution.
API Gateway supports 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 this certificate, you can request AWS Certificate Manager (ACM) to generate a new certificate in ACM or to import into ACM a custom certificate issued by a third-party certificate authority. 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.
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 custom domain name to its CloudFront distribution domain name. The mapping ensures that API requests against the custom domain name are routed through the correct CloudFront distribution.
A custom domain name associated with an API is region- and account-specific. Moving 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.
- Get Certificates Ready in AWS Certificate Manager
- Set Up a Custom Domain Name for an API Gateway API
- Log Custom Domain Name Creation in CloudTrail
- Configure Base Path Mapping of an API with a Custom Domain Name as its Host Name
- Rotate a Certificate Imported into ACM
- Call Your API with Custom Domain Names
Get Certificates Ready in AWS Certificate Manager
Before setting up a custom domain name for an API, you must have an SSL/TLS certificate ready in AWS Certificate Manager. The following steps describe how to get this done. For more information, see the AWS Certificate Manager User Guide.
To use an ACM Certificate with API Gateway, you must request or import the certificate
in the US East (N. Virginia) (
To get a certificate for a given domain name issued by or imported into ACM
Register your Internet domain; e.g.,
. You can use either Amazon Route 53 or a third-party accredited domain registrar. For a list of such registrar, see Accredited Registrar Directory at the ICANN website.
To create in or import into ACM an SSL/TLS certificate for a domain name, do one of the following:
To request a certificate provided by ACM for a domain name
Sign in to the AWS Certificate Manager console.
Choose Request a certificate.
Type a custom domain name for your API; e.g.,
api.myDomain.com, in Domain name.
Optionally, choose Add another name to this certificate.
Choose Review and request.
Choose Confirm and request.
For a valid request, a registered owner of the Internet domain must consent to the request before ACM issues the certificate.
To import into ACM a certificate for a domain name
Get a PEM-encoded SSL/TLS certificate for your custom domain name from a certificate authority. For a partial list, see Third-Party Certificate Authorities at the DMOZ website.
Generate a private key for the certificate and save the output to a file, using the OpenSSL toolkit at the OpenSSL website:Copy
openssl genrsa -out
Amazon API Gateway leverages Amazon CloudFront to support certificates for custom domain names. As such, the requirements and constraints of a custom domain name SSL/TLS certificate are dictated by CloudFront. For example, the maximum size of the public key is 2048 and the private key size can be 1024, 2048, and 4096. The public key size is determined by the certificate authority you use. Ask your certificate authority to return keys of a size different from the default length. For more information, see Secure access to your objects and Create signed URLs and signed cookies.
Generate a certificate signing request (CSR) with the previously generated private key, using OpenSSL:Copy
openssl req -new -sha256 -key
Submit the CSR to the certificate authority and save the resulting certificate.
Download the certificate chain from the certificate authority.
If you obtain the private key in another way and the key is encrypted, you can use the following command to decrypt the key before submitting it to API Gateway for setting up a custom domain name.Copy
openssl pkcs8 -topk8 -inform pem -in
MyEncryptedKey.pem-outform pem -nocrypt -out
Upload the certificate to AWS Certificate Manager:
Sign in to the AWS Certificate Manager console.
Choose Import a certificate.
For Certificate body, type or paste the body of the PEM-formatted server certificate from your certificate authority. The following shows an abbreviated example of such a certificate.Copy
-----BEGIN CERTIFICATE----- EXAMPLECA+KgAwIBAgIQJ1XxJ8Pl++gOfQtj0IBoqDANBgkqhkiG9w0BAQUFADBB ... az8Cg1aicxLBQ7EaWIhhgEXAMPLE -----END CERTIFICATE-----
For Certificate private key, type or paste your PEM-formatted certificate's private key. The following shows an abbreviated example of such a key.Copy
-----BEGIN RSA PRIVATE KEY----- EXAMPLEBAAKCAQEA2Qb3LDHD7StY7Wj6U2/opV6Xu37qUCCkeDWhwpZMYJ9/nETO ... 1qGvJ3u04vdnzaYN5WoyN5LFckrlA71+CszD1CGSqbVDWEXAMPLE -----END RSA PRIVATE KEY-----
For Certificate chain, type or paste the PEM-formatted intermediate certificates and, optionally, the root certificate, one after the other without any blank lines. If you include the root certificate, your certificate chain must start with intermediate certificates and end with the root certificate. Use the intermediate certificates provided by your certificate authority. Do not include any intermediaries that are not in the chain of trust path. The following shows an abbreviated example.Copy
-----BEGIN CERTIFICATE----- EXAMPLECA4ugAwIBAgIQWrYdrB5NogYUx1U9Pamy3DANBgkqhkiG9w0BAQUFADCB ... 8/ifBlIK3se2e4/hEfcEejX/arxbx1BJCHBvlEPNnsdw8EXAMPLE -----END CERTIFICATE-----
Here is another example.Copy
Intermediate certificate 2-----END CERTIFICATE----- -----BEGIN CERTIFICATE-----
Intermediate certificate 1-----END CERTIFICATE----- -----BEGIN CERTIFICATE-----
Optional: Root certificate-----END CERTIFICATE-----
Choose Review and import.
After the certificate is successfully created or imported, make note of the certificate ARN. You need it when setting up the custom domain name, next.
Set Up a Custom Domain Name for an API Gateway API
The following procedure describes how to set up a custom domain name for an API using the API Gateway console.
To set up a custom domain name using the API Gateway console
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.
Choose Custom Domain Names from the main navigation pane.
Choose Create Custom Domain Name next.
Under New Custom Domain Name, type your domain name (for example,
api.myDomain.com) in Domain Name.
Choose a certificate from the ACM Certificate list.
Choose Add mapping under Base Path Mappings to set a base path (Path) for a deployed API in a given stage (selected from the Destination dropdown lists.) You can also set the base path mapping after the custom domain name is created. For more information, see Configure Base Path Mapping of an API with a Custom Domain Name as its Host Name.
After the custom domain name is created, the console displays the associated CloudFront distribution domain name, in the form of
, along with the certificate ARN. Note the CloudFront distribution domain name shown in the output. You need it in the next step to set the custom domain's CNAME value or A-record alias target in your DNS.
The newly created custom domain name takes about 40 minutes to be ready. In the meantime, you can configure the DNS record alias to map the custom domain name to the associated CloudFront distribution domain name and to set up the base path mapping for the custom domain name while the custom domain name is being initialized.
In this step, we use Amazon Route 53 as an example DNS provider to show how to set up an A-record alias for your Internet domain to map the custom domain name to the associated CloudFront distribution name. The instructions can be adapted to other DNS providers.
Sign in to the Amazon Route 53 console.
A-IPv4 addressrecord set for your custom domain (e.g.,
api.example.com). An A-record maps a custom domain name to an IP4 address.
Choose Yes for Alias, type the CloudFront domain name (e.g.,
d3boq9ikothtgw.cloudfront.net) in Alias Target, and then choose Create. The A-record alias here maps your custom domain name to the specified CloudFront domain name that is itself mapped to an IP4 address.
For most DNS providers, a custom domain name is added to the hosted zone as a CNAME resource record set. The CNAME record name specifies the custom domain name you typed earlier in Domain Name (for example,
api.example.com). The CNAME record value specifies the domain name for the CloudFront distribution. However, use of a CNAME record will not work if your custom domain is a zone apex (i.e.,
api.example.com). A zone apex is also commonly known as the root domain of your organization. For a zone apex you need to use an A-record alias, provided that is supported by your DNS provider.
With Amazon Route 53 you can create an A record alias for your custom domain name and specify the CloudFront distribution domain name as the alias target, as shown above. This means that Amazon Route 53 can route your custom domain name even if it is a zone apex. For more information, see Choosing Between Alias and Non-Alias Resource Record Sets in the Amazon Route 53 Developer Guide.
Use of A-record aliases also eliminates exposure of the underlying CloudFront distribution domain name because the domain name mapping takes place solely within Amazon Route 53. For these reasons, we recommend that you use Amazon Route 53 A-record alias whenever possible.
In addition to using the API Gateway console, you can use the API Gateway REST API, AWS CLI or one of the AWS SDKs to set up the custom domain name for your APIs. As an illustration, the following procedure outlines the steps to do so using the REST API calls.
To set up a custom domain name using the API Gateway REST API
Call domainname:create, specifying the custom domain name and the ARN of a certificate stored in AWS Certificate Manager.
The successful API call returns a
201 Createdresponse containing the certificate ARN as well as the associated CloudFront distribution name in its payload.
Note the CloudFront distribution domain name shown in the output. You need it in the next step to set the custom domain's CNAME value or A-record alias target in your DNS.
Follow Step 6 of the previous procedure to set up an A-record alias to map the custom domain name to its CloudFront distribution name.
For code examples of this REST API call, see domainname:create.
Log Custom Domain Name Creation in CloudTrail
When CloudTrail is enabled for logging API Gateway calls made by your account, API Gateway logs the associated CloudFront distribution updates when a custom domain name is created or updated for an API. Because these CloudFront distributions are owned by API Gateway, each of these reported CloudFront distributions is identified by one of the following region-specific API Gateway account IDs, instead of the API owner's account ID.
Region-specific API Gateway account IDs of CloudFront distributions associated with a custom domain name
Configure Base Path Mapping of an API with a Custom Domain Name as its Host Name
You can use a single custom domain name as the host name of multiple APIs. You achieve this by configuring the base path mappings on the custom domain name. With the base path mappings, an API under the custom domain is accessible through the combination of the custom domain name and the associated base path.
For example, if you created an API named
PetStore and another API named
PetShop and set up a custom domain name of
in API Gateway, you can set the
PetStore API's URL as
PetStore API is
associated with the base path of an empty string or
myStore under the
custom domain name of
api.example.com. Similarly, you can assign a base
yourPetStore for the
PetShop API. The URL of
https://api.example.com/yourPetStore is then the root URL of the
Before setting the base path for an API, complete the steps in Set Up a Custom Domain Name for an API Gateway API.
To set the base path for API mappings using the API Gateway console
Choose a custom domain name from the list of available Custom Domain Names list under your account.
Choose Show Base Path Mappings or Edit.
Choose Add mapping.
(Optional) Type a base path name for Path, choose an API from Destination, and then choose a stage.
The Destination list shows the deployed APIs under your account.
Choose Save to finish setting up the base path mapping for the API.
To delete a mapping after you create it, next to the mapping that you want to delete, choose the trash icon.
In addition, you can call the API Gateway REST API, AWS CLI, or one of the AWS SDKs to set up the base path mapping of an API with a custom domain name as its host name. As an illustration, the following procedure outlines the steps to do so using the REST API calls.
To set up the base path mapping of an API using the API Gateway REST API
Call basepathmapping:create on a specific custom domain name, specifying the
restApiId, and a deployment
stageproperty in the request payload.
The successful API call returns a
For code examples of the REST API call, see basepathmapping:create.
Rotate a Certificate Imported into ACM
ACM automatically handles renewal of certificates it issues. You do not need to rotate any ACM-issued certificates for your custom domain names. CloudFront handles it on your behalf.
However, if you import a certificate into ACM and use it for a custom domain name, you must rotate the certificate before it expires. This involves importing a new third-party certificate for the domain name and rotate the existing certificate to the new one. You need to repeat the process when the newly imported certificate expires. Alternatively, you can request ACM to issue a new certificate for the domain name and rotate the existing one to the new ACM-issued certificate. After that, you can leave ACM and CloudFront to handle the certificate rotation for you automatically. To create or import a new ACM Certificate, follow the steps to request or import a new ACM Certificate for the specified domain name.
To rotate a certificate for a domain name, you can use the API Gateway console, the API Gateway REST API, AWS CLI, or one of the AWS SDKs.
To rotate an expiring certificate imported into ACM using the API Gateway console
Request or import a certificate in ACM.
Go back to the API Gateway console.
Choose Custom Domain Names from the API Gateway console main navigation pane.
Select the custom domain name of your choice, under the Custom Domain Names pane.
Choose the desired certificate from the ACM Certificate dropdown list.
Choose Save to begin rotating the certificate for the custom domain name.
It takes about 40 minutes for the process to finish. After the rotation is done, you can choose the two-way arrow icon next to ACM Certificate to roll back to the original certificate.
To illustrate how to programmatically rotate an imported certificate for a custom domain name, we outline the steps using the API Gateway REST API.
Rotate an imported certificate using the API Gateway REST API
Call domainname:update action, specifying the ARN of the new ACM Certificate for the specified domain name.
Call Your API with Custom Domain Names
Calling an API with a custom domain name is the same as calling the API with its default domain name, provided that the correct URL is used.
The following examples compare and contrast a set of default URLs and corresponding
custom URLs of two APIs (
qf3duz) in a
specified region (
us-east-1), and of a given custom domain name
Root URLs of APIs with default and custom domain names
|API ID||Stage||Default URL||Base path||Custom URL|
API Gateway supports custom domain names for an API by using Server Name Indication (SNI). You can invoke the API with a custom domain name using a browser or a client library that supports SNI.
API Gateway enforces SNI on the CloudFront distribution. For information on how CloudFront uses custom domain names, see Amazon CloudFront Custom SSL.