Articles

Add a Custom Domain to API Gateway (2026)

April 16, 2026 4 min read

API Gateway is a managed service that acts as a front door for your applications to access backend services. It handles tasks like request routing, authentication, and rate limiting. When you create an API Gateway API, it gets a default execute-api domain name. However, for production applications, you usually want to use your own custom domain, like api.example.com.

Let’s see how that looks in practice. Imagine you have a simple Lambda function that returns "Hello, World!".

{
  "statusCode": 200,
  "body": "Hello, World!"
}

When you deploy this through API Gateway, you’ll get a default URL like:

https://xxxxxxxxx.execute-api.us-east-1.amazonaws.com/prod

This URL is functional but not ideal for branding or security. You want to use https://api.example.com.

Here’s the process of adding a custom domain to API Gateway:

  1. Acquire an SSL/TLS Certificate: API Gateway requires an SSL/TLS certificate to serve traffic over HTTPS for your custom domain. You can obtain this from AWS Certificate Manager (ACM).

    • Navigate to the ACM console.
    • Request a public certificate.
    • Enter your domain name (e.g., api.example.com or *.example.com for a wildcard).
    • Choose DNS validation or email validation. DNS validation is generally preferred as it’s automated. If you use DNS validation, ACM will provide CNAME records you need to add to your DNS provider’s zone file.
    • Once the certificate is issued, it’s ready to be used. Important: The certificate must be in the us-east-1 (N. Virginia) region for Edge-optimized API Gateway endpoints, or in the same region as your Regional API Gateway endpoint.

  2. Create the Custom Domain Name in API Gateway:

    • Go to the API Gateway console.
    • In the navigation pane, choose "Custom domain names."
    • Click "Create."
    • Domain name: Enter your desired custom domain (e.g., api.example.com).
    • Minimum TLS version: Select a TLS version. TLS 1.2 is the current recommended standard.
    • Endpoint configuration:
      • Edge-optimized: This uses CloudFront distribution managed by API Gateway. It’s good for global reach.
      • Regional: This deploys the API to a specific AWS region. It’s simpler and can offer lower latency if your users are primarily in that region.
    • ACM certificate: Select the certificate you created in step 1.
    • Click "Create domain name."

  3. Configure API Mappings: After creating the custom domain, you need to map it to your API. This tells API Gateway which API and stage to route requests to when they arrive at your custom domain.

    • Select your newly created custom domain name from the list.
    • Go to the "API mappings" tab.
    • Click "Configure API mappings."
    • Click "Add new mapping."
    • API: Select the API Gateway API you want to associate with this domain.
    • Stage: Select the deployment stage (e.g., prod, dev).
    • Path (Optional): You can specify a path prefix. For example, if you set this to v1, then requests to https://api.example.com/v1/your/resource would be routed to your API’s /your/resource path. If left blank, requests to https://api.example.com/your/resource go to your API’s /your/resource path.
    • Click "Save."

  4. Update DNS Records: The final step is to point your custom domain’s DNS records to the API Gateway endpoint.

    • After creating the custom domain name in API Gateway, you’ll see an "API Gateway domain name" (e.g., d-xxxxxxxxxx.execute-api.us-east-1.amazonaws.com). This is the target for your DNS record.
    • Go to your DNS provider (e.g., Amazon Route 53, GoDaddy, Cloudflare).
    • Create a new record set for your custom domain.
    • Type: A record (if using Route 53 with Alias) or CNAME.
    • Name: Your custom domain name (e.g., api.example.com).
    • Value/Alias Target:
      • If using Route 53, you can create an A record and choose "Alias" to API Gateway API and select your custom domain’s API Gateway domain name. This is the recommended approach as it handles IP address changes automatically.
      • If using another DNS provider or not using an alias, create a CNAME record pointing to the "API Gateway domain name" provided by API Gateway.
    • Save the DNS record. DNS propagation can take some time (from a few minutes to 48 hours, though usually much faster).

Once DNS has propagated, you should be able to access your API Gateway API using your custom domain name: https://api.example.com/your/resource.

The surprising thing about custom domains is that for Edge-optimized endpoints, API Gateway automatically provisions and manages a CloudFront distribution for you behind the scenes, which is why the certificate must be in us-east-1. For Regional endpoints, there’s no CloudFront involved, and the certificate needs to be in the same region as your API.

The next thing you’ll likely want to configure is API caching to improve performance and reduce the load on your backend services.

Want structured learning?

Take the full Apigateway course →