Setting up custom domain names for HTTP APIs
Custom domain names are simpler and more intuitive URLs that you can provide to your API users.
After deploying your API, you (and your customers) can invoke the API using the default base URL of the following format:
https://
api-id
.execute-api.region
.amazonaws.com/stage
where api-id
is generated by API Gateway, region
(AWS Region) is specified by you
when creating the API, and stage
is specified by you when deploying the
API.
The hostname portion of the URL (that is,
)
refers to an API endpoint. The default API endpoint
can be difficult to recall and not user-friendly.api-id
.execute-api.region
.amazonaws.com
With custom domain names, you can set up your API's hostname, and choose a base path (for
example, myservice
) to map the alternative URL to your API. For example, a more
user-friendly API base URL can become:
https://api.example.com/myservice
Note
A custom domain can be associated with REST APIs and HTTP APIs. You can use API Gateway Version 2 APIs to create and manage Regional custom domain names for REST APIs and HTTP APIs.
For HTTP APIs, TLS 1.2 is the only supported TLS version.
Register a domain name
You must have a registered internet domain name in order to set up custom domain names for
your APIs. Your domain name must follow the RFC
1035
After a custom domain name is created in API Gateway, you must create or update your DNS provider's resource record to map to your API endpoint. Without such a mapping, API requests bound for the custom domain name cannot reach API Gateway.
Regional custom domain names
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. You must also provide a certificate for the custom domain name.
Wildcard custom domain names
With wildcard custom domain names, you can support an almost infinite number of domain names without exceeding
the default quota. For example, you could give each of your customers their own
domain name,
.customername
.api.example.com
To create a wildcard custom domain name, specify a wildcard (*
) as the first subdomain of a
custom domain that represents all possible subdomains of a root domain.
For example, the wildcard custom domain name *.example.com
results in subdomains such as
a.example.com
, b.example.com
, and c.example.com
, which all route to the
same domain.
Wildcard custom domain names support distinct configurations from API Gateway's standard custom domain names.
For example, in a single AWS account, you can configure *.example.com
and
a.example.com
to behave differently.
To create a wildcard custom domain name, you must provide a certificate issued by ACM that has been validated using either the DNS or the email validation method.
Note
You can't create a wildcard custom domain name if a different AWS account has created a custom domain
name that conflicts with the wildcard custom domain name. For example, if account A has created
a.example.com
, then account B can't create the wildcard custom domain name
*.example.com
.
If account A and account B share an owner, you can contact the AWS
Support Center
Certificates for custom domain names
Important
You specify the certificate for your custom domain name. If your application uses certificate pinning, sometimes known as SSL pinning, to pin an ACM certificate, the application might not be able to connect to your domain after AWS renews the certificate. For more information, see Certificate pinning problems in the AWS Certificate Manager User Guide.
To provide a certificate for a 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. You create a certificate for the given domain name (or import a certificate), 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.
For details on setting up a custom domain name, see Getting certificates ready in AWS Certificate Manager and Setting up a regional custom domain name in API Gateway.