You want an API Gateway API served at https://api.example.com instead of its default execute-api URL. What do you configure, and why does the endpoint type decide which region the ACM certificate must live in?

middlenice to knowfreq 32%

answer

hostname, mapping, DNS record
who terminates the TLS decides
edge-optimized means CloudFront in front
CloudFront reads certificates from one region only
the default endpoint stays live unless disabled

basics

~20 s

Create an API Gateway custom domain name with an ACM certificate, add a base-path/API mapping to a specific API and stage, then point DNS at the target domain the service returns. An edge-optimized domain is fronted by CloudFront, so its certificate must be in us-east-1; a regional domain needs the certificate in the API's own region.

solid answer

~50 s

Three pieces. First, a custom domain name resource in API Gateway, holding the hostname and an ACM certificate. Second, a mapping from that domain to an API and stage — base path mappings on REST APIs, API mappings on HTTP APIs — which is what lets api.example.com/orders and api.example.com/billing reach two different APIs behind one hostname. Third, a DNS record (usually a Route 53 alias) pointing the hostname at the target domain name API Gateway hands back, not at your API id. The certificate region follows from the endpoint type because of who terminates TLS: an edge-optimized custom domain is served through CloudFront, and CloudFront only reads certificates from us-east-1; a regional custom domain terminates in the API's own region, so the certificate must be issued or imported there. Worth knowing too: the default execute-api hostname keeps working alongside the custom domain unless you set disableExecuteApiEndpoint.

Three pieces. First, a **custom domain name** resource in API Gateway, holding the hostname and an ACM certificate. Second, a **mapping** from that domain to an API and stage — base path mappings on REST APIs, API mappings on HTTP APIs — which is what lets `api.example.com/orders` and `api.example.com/billing` reach two different APIs behind one hostname. Third, a **DNS record** (usually a Route 53 alias) pointing the hostname at the target domain name API Gateway hands back, not at your API id. The certificate region follows from the endpoint type because of who terminates TLS: an **edge-optimized** custom domain is served through CloudFront, and CloudFront only reads certificates from **us-east-1**; a **regional** custom domain terminates in the API's own region, so the certificate must be issued or imported there. Worth knowing too: the default `execute-api` hostname keeps working alongside the custom domain unless you set `disableExecuteApiEndpoint`.

code

bash · 10 lines

bash

# Regional custom domain: certificate must live in the API's own region
aws apigatewayv2 create-domain-name \
  --domain-name api.example.com \
  --domain-name-configurations \
      CertificateArn=arn:aws:acm:eu-west-1:111122223333:certificate/abc-123,EndpointType=REGIONAL,SecurityPolicy=TLS_1_2

# Bind a path on that hostname to one API and stage
aws apigatewayv2 create-api-mapping \
  --domain-name api.example.com \
  --api-id a1b2c3d4e5 --stage prod --api-mapping-key orders

go deeper

for a junior

Know that the default execute-api URL is not a public contract, and that a custom domain needs a certificate, a mapping to an API and stage, and a DNS record.

for a middle

Explain why edge-optimized domains need a us-east-1 certificate (CloudFront terminates the TLS) while regional domains need one in the API's own region, and how base path mappings host several APIs on one hostname.

for a senior

Use the domain as the migration seam: repoint mappings for cutovers, and close the default endpoint with disableExecuteApiEndpoint so mutual TLS or a WAF in front cannot be walked around.

for a principal

Set the naming and exposure standard for the estate — who owns the public hostnames, how certificates are issued and renewed, and whether edge-optimized or a self-managed CloudFront layer is the org default given your multi-region plans.

What the default endpoint gives you and why it is not enough

Every API is reachable at https://{api-id}.execute-api.{region}.amazonaws.com/{stage}. That is fine for testing and unacceptable as a public contract: the hostname leaks the region, embeds a random id that changes if the API is recreated, and forces the stage into the path. A custom domain name fixes all three.

The three moving parts

1. The custom domain name resource. You create it in API Gateway with the hostname and an ACM certificate, choosing an endpoint type. It is a first-class resource independent of any API — which is precisely what makes cutovers possible.

2. The mapping. A REST API uses base path mappings; an HTTP API uses API mappings. Either way you bind {domain, base path} to {api, stage}. One domain can host several APIs on different paths, and the empty base path acts as the catch-all. This is also the safest place to run a migration: build the new API, point a mapping at it, and flip the base path when ready — clients never see a hostname change.

3. DNS. API Gateway returns a target domain name — something like d-a1b2c3d4e5.execute-api.eu-west-1.amazonaws.com for a regional domain, or a CloudFront distribution hostname for an edge-optimized one. In Route 53 you create an alias A record to that target (alias, not CNAME, so the apex works and there is no extra lookup). Outside Route 53 a CNAME on a subdomain does the job.

Why the certificate's region depends on the endpoint type

Because it depends on who terminates the TLS connection.

Edge-optimized: the hostname resolves to a CloudFront distribution that API Gateway manages on your behalf. Traffic enters at the nearest edge location and rides the AWS backbone to the API's region. CloudFront can only use ACM certificates issued in us-east-1, so an edge-optimized custom domain's certificate must be requested there even when the API runs in Sydney.
Regional: the hostname resolves straight to API Gateway in one region, which terminates TLS itself, so the certificate must exist in that region. It is not copied for you — ACM certificates do not cross regions.

Getting this wrong is the single most common stumble: the console simply will not offer the certificate you created, and people conclude ACM issuance failed.

The endpoint type is also a design decision, not just a certificate detail. Edge-optimized cuts TLS-handshake latency for globally distributed clients. Regional gives you control — you can put your own CloudFront distribution in front (with your own cache behaviours and WAF), or use latency-based Route 53 records across several regional deployments for multi-region active-active. Note that HTTP APIs support regional custom domains only.

The bypass nobody notices

Creating a custom domain does not retire the default endpoint. https://{api-id}.execute-api... stays live, which means any control you attached at the domain — mutual TLS, or your own CloudFront distribution carrying a WAF web ACL — can be walked around by a caller who discovers the raw hostname. The fix is the disableExecuteApiEndpoint property on the API, which turns the default hostname off and leaves only the custom domain path. In a security review, "we put WAF on the CloudFront distribution in front" is an incomplete answer until that flag is set.

bash

aws apigatewayv2 update-api --api-id a1b2c3d4e5 --disable-execute-api-endpoint

Other settings worth naming

Security policy — the minimum TLS version the domain will negotiate (for example TLS_1_2).
Mutual TLS — client-certificate authentication, configured on the custom domain with a truststore bundle in S3. It is only available on custom domains, which is another reason to have one.
Wildcard certificates — a single *.example.com certificate can back several custom domain names, though a given wildcard domain and an explicit subdomain of it cannot both be created across accounts.

The operational payoff

The reason to insist on a custom domain early is not vanity. It decouples the public contract from the resource: you can recreate an API, move it to a different type, or shift it to a new region, and change nothing that clients hold. Teams that publish the raw execute-api URL discover the cost of that shortcut later, when the only way to migrate is to ask every consumer to redeploy.

## What the default endpoint gives you and why it is not enough Every API is reachable at `https://{api-id}.execute-api.{region}.amazonaws.com/{stage}`. That is fine for testing and unacceptable as a public contract: the hostname leaks the region, embeds a random id that changes if the API is recreated, and forces the stage into the path. A custom domain name fixes all three. ## The three moving parts **1. The custom domain name resource.** You create it in API Gateway with the hostname and an ACM certificate, choosing an endpoint type. It is a first-class resource independent of any API — which is precisely what makes cutovers possible. **2. The mapping.** A REST API uses **base path mappings**; an HTTP API uses **API mappings**. Either way you bind `{domain, base path}` to `{api, stage}`. One domain can host several APIs on different paths, and the empty base path acts as the catch-all. This is also the safest place to run a migration: build the new API, point a mapping at it, and flip the base path when ready — clients never see a hostname change. **3. DNS.** API Gateway returns a *target domain name* — something like `d-a1b2c3d4e5.execute-api.eu-west-1.amazonaws.com` for a regional domain, or a CloudFront distribution hostname for an edge-optimized one. In Route 53 you create an **alias A record** to that target (alias, not CNAME, so the apex works and there is no extra lookup). Outside Route 53 a CNAME on a subdomain does the job. ## Why the certificate's region depends on the endpoint type Because it depends on **who terminates the TLS connection**. - **Edge-optimized**: the hostname resolves to a CloudFront distribution that API Gateway manages on your behalf. Traffic enters at the nearest edge location and rides the AWS backbone to the API's region. CloudFront can only use ACM certificates issued in **us-east-1**, so an edge-optimized custom domain's certificate must be requested there even when the API runs in Sydney. - **Regional**: the hostname resolves straight to API Gateway in one region, which terminates TLS itself, so the certificate must exist **in that region**. It is not copied for you — ACM certificates do not cross regions. Getting this wrong is the single most common stumble: the console simply will not offer the certificate you created, and people conclude ACM issuance failed. The endpoint type is also a design decision, not just a certificate detail. Edge-optimized cuts TLS-handshake latency for globally distributed clients. Regional gives you control — you can put your own CloudFront distribution in front (with your own cache behaviours and WAF), or use latency-based Route 53 records across several regional deployments for multi-region active-active. Note that HTTP APIs support regional custom domains only. ## The bypass nobody notices Creating a custom domain does **not** retire the default endpoint. `https://{api-id}.execute-api...` stays live, which means any control you attached at the domain — mutual TLS, or your own CloudFront distribution carrying a WAF web ACL — can be walked around by a caller who discovers the raw hostname. The fix is the `disableExecuteApiEndpoint` property on the API, which turns the default hostname off and leaves only the custom domain path. In a security review, "we put WAF on the CloudFront distribution in front" is an incomplete answer until that flag is set. ```bash aws apigatewayv2 update-api --api-id a1b2c3d4e5 --disable-execute-api-endpoint ``` ## Other settings worth naming - **Security policy** — the minimum TLS version the domain will negotiate (for example `TLS_1_2`). - **Mutual TLS** — client-certificate authentication, configured on the custom domain with a truststore bundle in S3. It is only available on custom domains, which is another reason to have one. - **Wildcard certificates** — a single `*.example.com` certificate can back several custom domain names, though a given wildcard domain and an explicit subdomain of it cannot both be created across accounts. ## The operational payoff The reason to insist on a custom domain early is not vanity. It decouples the public contract from the resource: you can recreate an API, move it to a different type, or shift it to a new region, and change nothing that clients hold. Teams that publish the raw `execute-api` URL discover the cost of that shortcut later, when the only way to migrate is to ask every consumer to redeploy.

After adding a custom domain with mutual TLS, how do you stop clients from bypassing it?
Set `disableExecuteApiEndpoint` on the API. The default `{api-id}.execute-api...` hostname remains live otherwise, and a caller who finds it reaches the API without the client certificate, the TLS policy, or any WAF you attached in front of the custom domain. Turning it off leaves the custom domain as the only path in.
How would you migrate consumers from an old API to a rebuilt one with no client changes?
Keep the custom domain fixed and move the mapping. Build the new API, attach it to a temporary base path or a test domain to validate, then repoint the production base path mapping at the new API and stage. Clients keep calling the same hostname, and rollback is repointing the mapping back.
When would you choose a regional custom domain over an edge-optimized one?
When you want to own the edge yourself: your own CloudFront distribution with custom cache behaviours and a WAF web ACL, or latency-based Route 53 routing across several regional deployments for multi-region availability. Edge-optimized is the simpler default for globally spread clients who mainly benefit from a shorter TLS handshake.

saying these in an interview costs you the question

Requests the certificate in the API's region for an edge-optimized domain
Assumes the default execute-api URL stops working automatically
Points DNS at the API id rather than the returned target domain
Thinks one custom domain can front only one API
Believes ACM certificates are usable from any region

You want an API Gateway API served at https://api.example.com instead of its default execute-api URL. What do you configure, and why does the endpoint type decide which region the ACM certificate must live in?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

What the default endpoint gives you and why it is not enough

The three moving parts

Why the certificate's region depends on the endpoint type

The bypass nobody notices

Other settings worth naming

The operational payoff

▾common follow-ups3 questions

▾red flags5 flags

§ context

▾related questions5 questions

▾related topics4 topics

What the default endpoint gives you and why it is not enough

The three moving parts

Why the certificate's region depends on the endpoint type

The bypass nobody notices

Other settings worth naming

The operational payoff

answer

go deeper

context