Custom domain names for private APIs in API Gateway - Amazon API Gateway
Securing your certificate's private key for your custom domain nameConsiderations for private custom domain namesConsiderations for using private custom domain names with other API Gateway resourcesDifferences between private custom domain names and public custom domain namesNext steps for custom domain names for private APIs
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Custom domain names for private APIs in API Gateway

You can create a custom domain name for your private APIs. Use a private custom domain name to provide API callers with a simpler and more intuitive URL. With a private custom domain name, you can reduce complexity, configure security measures during the TLS handshake, and control the certificate lifecycle of your domain name using Amazon Certificate Manager (ACM). For more information, see Securing your certificate's private key for your custom domain name.

Custom domain names for private APIs don’t need to be unique across multiple accounts. You can create example.private.com in account 111122223333 and in account 555555555555, as long as your ACM certificate covers the domain name. To identify a private custom domain name, use the private custom domain name ARN. This identifier is unique to private custom domain names.

When you create a private custom domain name in API Gateway, you're an API provider. You can provide your private custom domain name to other Amazon Web Services accounts using API Gateway or Amazon Resource Access Manager (Amazon RAM).

When you invoke a private custom domain name, you're an API consumer. You can consume a private custom domain name from your own Amazon Web Services account or from another Amazon Web Services account.

When you consume a private custom domain name, you create a domain name access association between a VPC endpoint and a private custom domain name. With a domain name access association, API consumers can invoke your private custom domain name while isolated from the public internet. For more information, see Tasks of API providers and API consumers for custom domain names for private APIs.

Securing your certificate's private key for your custom domain name

When you request an SSL/TLS certificate using ACM to create your custom domain name for private APIs, ACM generates a public/private key pair. When you import a certificate, you generate the key pair. The public key becomes part of the certificate. To safely store the private key, ACM creates another key using Amazon KMS, called the KMS key, with the alias aws/acm. Amazon KMS uses this key to encrypt your certificate’s private key. For more information, see Data protection in Amazon Certificate Manager in the Amazon Certificate Manager User Guide.

API Gateway uses Amazon TLS Connection Manager, a service that is only accessible only to Amazon Web Services services, to secure and use your certificate's private keys. When you use your ACM certificate to create a API Gateway custom domain name, API Gateway associates your certificate with Amazon TLS Connection Manager. We do this by creating a grant in Amazon KMS against your Amazon managed key. This grant allows TLS Connection Manager to use Amazon KMS to decrypt your certificate's private key. TLS Connection Manager uses the certificate and the decrypted (plaintext) private key to establish a secure connection (SSL/TLS session) with clients of API Gateway services. When the certificate is disassociated from a API Gateway service, the grant is retired. For more information, see Grants in the Amazon Key Management Service Developer Guide.

For more information, see Data encryption at rest in Amazon API Gateway.

Considerations for private custom domain names

The following considerations might impact your use of private custom domain names.

  • To invoke a private custom domain name, you must create a domain name access association. After you create a domain name access association, it takes about 15 minutes to be ready.

  • You can't invoke private custom domain names with the same name from the same VPC endpoint. For example, if you wanted to invoke arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 and arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+xyz000, associate each private custom domain name with a different VPC endpoint.

  • Wildcard certificates are supported, such as a certificate for *.example.private.com.

  • Wildcard custom domain names aren't supported.

  • You can send traffic using all IP address types supported by Amazon VPC. You can send dualstack and IPv6 traffic by configuring the settings on your VPC endpoint. You can't modify this using API Gateway. For more information, see Add IPv6 support for your VPC.

  • Custom domain names for private APIs are not supported in Asia Pacific (Malaysia).

  • Multi-level base path mapping, such as mapping your private API to /developers/feature, isn't supported.

  • You can’t set a minimum TLS version for your private custom domain name. All private custom domain names have the security policy of TLS-1-2.

  • You can use VPC endpoint policy to control access to a private custom domain name. For more information, see examples 4 and 5 in Use VPC endpoint policies for private APIs in API Gateway.

  • You must create a separate resource policy for your private API and for your private custom domain name. To invoke a private custom domain name, an API consumer needs access from the private custom domain name resource policy, the private API resource policy, and any VPC endpoint policies or authorization on the private API.

Considerations for using private custom domain names with other API Gateway resources

The following considerations might impact how you use private custom domain names with other API Gateway resources.

  • You can't map a public API to a private custom domain name.

  • When a private API is mapped to a private custom domain name, you can't change the API's endpoint type.

  • You can't migrate a public custom domain name to a private custom domain name.

  • If you have a VPC endpoint that you use to access a public custom domain name, don't use it to create a domain name access association with a private custom domain name.

Differences between private custom domain names and public custom domain names

The following describes the differences between private and public custom domain names.

  • Private custom domain names don’t need to be unique across multiple accounts.

  • A private domain name has an ARN and a domain name ID. These identifiers uniquely identify a private custom domain name and aren't generated for public custom domain names.

  • When you use the Amazon CLI to update or delete your private custom domain name, you must provide the domain name ID. If you have a private custom domain name called example.com and a public custom domain name called example.com and you don't provide the domain name ID, API Gateway will modify or delete your public custom domain name.

Next steps for custom domain names for private APIs

For information about the tasks of an API provider and an API consumer, see Tasks of API providers and API consumers for custom domain names for private APIs.

For instructions on creating a private custom domain name that you can invoke in your own Amazon Web Services account, see Tutorial: Create and invoke a custom domain name for private APIs.

For instructions on providing another Amazon Web Services account access to your private custom domain name, see API provider: Share your private custom domain name using Amazon RAM. For instructions on associating your VPC endpoint with a private custom domain name in another Amazon Web Services account, see API consumer: Associate your VPC endpoint with a private custom domain name shared with you.