Menu
Amazon API Gateway
Developer Guide

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:

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

Here, the host name of the URL (i.e., api-id.execute-api.region.amazonaws.com) 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:

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

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.

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 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.

Note

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

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.

Note

To use an ACM Certificate with API Gateway, you must request or import the certificate in the US East (N. Virginia) (us-east-1) Region.

To get a certificate for a given domain name issued by or imported into ACM

  1. Register your Internet domain; e.g., myDomain.com. 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.

  2. 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

    1. Sign in to the AWS Certificate Manager console.

    2. Choose Request a certificate.

    3. Type a custom domain name for your API; e.g., api.myDomain.com, in Domain name.

    4. Optionally, choose Add another name to this certificate.

    5. Choose Review and request.

    6. Choose Confirm and request.

    7. 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

    1. 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.

      1. 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 private-key-file 2048

        Note

        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.

      2. Generate a certificate signing request (CSR) with the previously generated private key, using OpenSSL:

        Copy
        openssl req -new -sha256 -key private-key-file -out CSR-file
      3. Submit the CSR to the certificate authority and save the resulting certificate.

      4. Download the certificate chain from the certificate authority.

      Note

      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 MyDecryptedKey.pem
    2. Upload the certificate to AWS Certificate Manager:

      1. Sign in to the AWS Certificate Manager console.

      2. Choose Import a certificate.

      3. 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-----
      4. 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-----
      5. 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
        -----BEGIN CERTIFICATE----- Intermediate certificate 2 -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- Intermediate certificate 1 -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- Optional: Root certificate -----END CERTIFICATE-----
      6. Choose Review and import.

  3. 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

  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Choose Custom Domain Names from the main navigation pane.

  3. Choose Create Custom Domain Name next.

  4. 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.

    Choose Save.

  5. After the custom domain name is created, the console displays the associated CloudFront distribution domain name, in the form of distribution-id.cloudfront.net, 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.

    Note

    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.

  6. 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.

    1. Sign in to the Amazon Route 53 console.

    2. Create an A-IPv4 address record set for your custom domain (e.g., api.example.com). An A-record maps a custom domain name to an IP4 address.

    3. 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.

      
                                        Set a DNS record alias  for a custom domain name for an API
                                            in API Gateway

    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., example.com instead of 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

  1. 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 Created response containing the certificate ARN as well as the associated CloudFront distribution name in its payload.

  2. 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.

  3. 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

Region Account ID
us-east-1 392220576650
us-east-2 718770453195
us-west-1 968246515281
us-west-2 109351309407
eu-west-1 631144002099
eu-west-2 544388816663
eu-central-1 474240146802
ap-northeast-1 969236854626
ap-northeast-2 020402002396
ap-southeast-1 195145609632
ap-southeast-2 798376113853

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 api.example.com in API Gateway, you can set the PetStore API's URL as https://api.example.com or https://api.example.com/myPetStore. The 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 path of yourPetStore for the PetShop API. The URL of https://api.example.com/yourPetStore is then the root URL of the PetShop API.

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

  1. Choose a custom domain name from the list of available Custom Domain Names list under your account.

  2. Choose Show Base Path Mappings or Edit.

  3. Choose Add mapping.

  4. (Optional) Type a base path name for Path, choose an API from Destination, and then choose a stage.

    Note

    The Destination list shows the deployed APIs under your account.

  5. Choose Save to finish setting up the base path mapping for the API.

Note

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 basePath, restApiId, and a deployment stage property in the request payload.

    The successful API call returns a 201 Created response.

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

  1. Request or import a certificate in ACM.

  2. Go back to the API Gateway console.

  3. Choose Custom Domain Names from the API Gateway console main navigation pane.

  4. Select the custom domain name of your choice, under the Custom Domain Names pane.

  5. Choose Edit.

  6. Choose the desired certificate from the ACM Certificate dropdown list.

  7. Choose Save to begin rotating the certificate for the custom domain name.

    Note

    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 (udxjef and qf3duz) in a specified region (us-east-1), and of a given custom domain name (apis.domain.com).

Root URLs of APIs with default and custom domain names

API ID Stage Default URL Base path Custom URL
udxjef pro https://udxjef.execute-api.us-east-1.amazonaws.com/pro /petstore https://apis.domain.com/petstore
udxjef tst https://udxjef.execute-api.us-east-1.amazonaws.com/tst /petdepot https://apis.domain.com/petdepot
qf3duz dev https://qf3duz.execute-api.us-east-1.amazonaws.com/dev /bookstore https://apis.domain.com/bookstore
qf3duz tst https://qf3duz.execute-api.us-east-1.amazonaws.com/tst /bookstand https://apis.domain.com/bookstand

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.