Menu
Amazon API Gateway
Developer Guide

Use a Custom Domain Name in API Gateway

After deploying your API, you (and the client) can invoke the API using the default root URL of the https://api-id.execute-api.region.amazonaws.com format. 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) and choose a base path (e.g., myservice) to present an alternative URL (e.g., https://api.example.com/myservice) for the API. You can also use an empty base path for an API. In this case, the API's URL is the same as the custom domain (e.g., https://api.example.com.)

For every API you create, API Gateway sets up an Amazon CloudFront distribution for the API. Requests with the default API URL are routed to the corresponding CloudFront distribution. Similarly, every custom domain name is backed by a CloudFront distribution. An API request with the custom domain name passes through the custom domain name's CloudFront distribution before reaching the API's CloudFront distribution. API Gateway supports custom domain names for APIs 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 enable a custom domain name, you, as the API owner, must provide a server-side SSL certificate to verify the custom domain name targeted by the client requests. You do this when setting up the domain name initially and then when renewing an expiring certificate subsequently. In addition, you must have registered the custom domain name with a domain name registrar. After setting up a custom domain name 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. For the SSL certificate, you must also have obtained from a certificate authority the PEM-formatted SSL certificate body, its private key, and the certificate chain for the custom domain name. This section describes how to configure a domain name for an API, to set up the certificate for a custom domain name, to map a base path to an API, and to upload a new certificate to replace an expiring one. We will also provide general guidance, by way of examples, on how to obtain the server-side certificate and create a DNS record.

Note

Moving a custom domain between regions or AWS accounts requires 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.

Prerequisites

Note

API Gateway, fronted by CloudFront, does not support self-signed SSL certificates.

The following steps describe how to prepare to use custom domain names in API Gateway.

To prepare to use custom domain names in API Gateway

  1. Register your custom domain name. See the Accredited Registrar Directory at the ICANN website.

  2. Get a PEM-encoded SSL certificate for your custom domain name from a certificate authority. For a partial list, see Third-Party Certificate Authorities at the DMOZ website.

    Here are the general steps to obtain an SSL certificate from your chosen certificate authority:

    1. Generate a private key for the certificate and save output to a file, using the OpenSSL toolkit at the OpenSSL website:

      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 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 CA you use. Inquire your CA 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:

      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.

    openssl pkcs8 -topk8 -inform pem -in MyEncryptedKey.pem -outform pem -nocrypt -out MyDecryptedKey.pem

Set Up a Custom Domain Name for an API Gateway API

The following procedure describes how to set up a custom domain name.

To set up a custom domain name for an API Gateway API

  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 in the secondary navigation pane.

  4. In Create Custom Domain Name, specify the following:

    1. For Domain name, type your domain name (for example, api.example.com).

    2. For Certificate name, type a name for future reference (for example, my-example-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.

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

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

      -----BEGIN CERTIFICATE-----
      EXAMPLECA4ugAwIBAgIQWrYdrB5NogYUx1U9Pamy3DANBgkqhkiG9w0BAQUFADCB
      ...
      8/ifBlIK3se2e4/hEfcEejX/arxbx1BJCHBvlEPNnsdw8EXAMPLE
      -----END CERTIFICATE-----

      Here is another example.

      -----BEGIN CERTIFICATE-----
      Intermediate certificate 2
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      Intermediate certificate 1
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      Optional: Root certificate
      -----END CERTIFICATE-----
  5. Choose Save.

  6. While the new custom domain name is being created, the console displays the following information to have a resource record created in your DNS provider to map your custom domain name (api.example.com) to the API's CloudFront distribution domain name (distribution-id.cloudfront.net).

    Create a custom domain name for an API in API Gateway

    Make note of the CloudFront distribution's domain name shown in the output. You will need it to set the custom domain's CNAME value or A-record alias target in your DNS.

  7. In this step, we will use Amazon Route 53 as an example DNS provider to show how to set up an A-record alias to map the custom domain to its CloudFront distribution. The instructions can be adapted to other DNS providers.

    1. Go to the Amazon Route 53 console.

    2. If necessary, register a custom domain name.

    3. Create a hosted zone.

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

    5. 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, which 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 for 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 alternatively create an A record alias for your custom domain name and specify the CloudFront distribution as the alias target, as is 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.

Specify API Mappings for a Custom Domain Name

After you have set up a custom domain name, you must configure how individual APIs are invoked with the custom domain name. This amounts to specifying an API's URL with the given domain name. For example, if you have 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. This involves setting up the API's base path. The first example uses an empty base path and the second example uses myPetStore as the base path of the API, relative to the domain name. Similarly, you can use https://api.example.com/yourPetStore as the PetShop API's URL. The base path is yourPetShop. Thus, base paths can be used to host multiple APIs behind a single custom domain name.

Complete the steps in Set Up a Custom Domain Name for an API Gateway API before setting the base path for API mappings.

To set the base path for API mappings

  1. For each URL variation you want to enable, choose Create API mapping.

  2. (Optional) For Base path, type the base path name that API callers must provide as part of the URL. This value must be unique for all of the mappings across a single API. Leave this blank if you do not want callers to specify a base path name after the domain name.

  3. For API, choose the name of an available API from the selected region in your AWS account.

  4. (Optional) For Stage, choose the name of the API's stage you want to use for this mapping. Leave this blank if you want callers to explicitly specify the stage name after any base path name.

  5. Choose Save.

Note

To delete a mapping after you create it, next to the mapping that you want to delete, choose Remove.

Base Path Examples of API Mappings for a Custom Domain Name

The following examples use a custom domain name of api.example.com:

  • Leave Base Path blank, specify an API of MyDemoAPI, and specify a Stage value of prod to enable calls to https://api.example.com to be forwarded to https://my-api-id.execute-api.region-id.amazonaws.com/prod (where my-api-id is the identifier API Gateway assigns to the API named MyDemoAPI).

  • Leave Base Path blank, specify an API of MyDemoAPI, and leave Stage blank to enable calls to https://api.example.com/prod to be forwarded to https://my-api-id.execute-api.region-id.amazonaws.com/prod (where my-api-id is the identifier API Gateway assigns to the API named MyDemoAPI).

  • Specify a Base Path value of billing, specify an API of MyDemoAPI, and leave Stage blank to enable calls to https://api.example.com/billing/beta to be forwarded to https://my-api-id.execute-api.region-id.amazonaws.com/beta (where my-api-id is the identifier API Gateway assigns to the API named MyDemoAPI).

  • Specify a Base Path value of scheduling, specify an API of MyDemoAPI, and specify a Stage value of gamma to enable calls to https://api.example.com/scheduling to be forwarded to https://my-api-id.execute-api.region-id.amazonaws.com/gamma (where my-api-id is the identifier API Gateway assigns to the API named MyDemoAPI).

Upload and Renew an Expiring Certificate

The following steps describe how to upload and renew an expiring certificate for a custom domain name using the API Gateway console. You cannot rotate custom domain name certificates programmatically.

To upload a new certificate for a custom domain name

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

  2. Select a custom name under the Domain Names pane.

  3. Choose Upload

    Note

    The upload feature will not be available when the certificate is being initialized or rotated for the selected custom domain name. However, upload for a different domain name is still available because the upload feature is independent for each custom domain name.

  4. In Upload Backup Certificate for a-domain-name specify the following:

    • Type a name for the new certificate in Certificate name. The name should be different from the name of the expiring certificate.

    • Type or paste the PEM-formatted new certificate body in Certificate body.

    • Type or paste the PEM-formatted new certificate key in Certificate private key

    • Type or paste the PEM-formatted new certificate chain in Certificate chain.

    Then, choose Save.

  5. Choose Rotate to start replacing the old certificate by the new certificate.

    Note

    The certificate rotation takes up to 40 minutes to finish. The custom domain name is available during the rotation.

    Rotate a new certificate for a custom 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.

API Gateway supports custom domain names for an API by using Server Name Indication (SNI). After a custom domain name is configured with the API, you can call the API with the custom domain name by 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.