Skip to main content

Custom Domain

deployless can automatically provision an ACM certificate and configure a custom domain for your API Gateway.

Option 1: Route 53 (fully automatic)​

If your DNS is managed by Route 53, deployless creates the ACM certificate and validates it automatically — zero manual steps.

# Auto-detect hosted zone
api:
  domain:
    domain_name: api.myapp.com
    route53: true
# Explicit hosted zone ID
api:
  domain:
    domain_name: api.myapp.com
    route53:
      hosted_zone_id: Z1234567890ABC

With route53: true, deployless uses boto3 to find the Route 53 hosted zone that matches your domain. If you have multiple hosted zones, provide the hosted_zone_id explicitly.

Cost: ACM certificate is free. Route 53 hosted zone costs ~$0.50/month (if you already have it, there is no additional cost).

Option 2: External DNS (Cloudflare, GoDaddy, etc.)​

If your DNS is managed outside AWS, deployless guides you through a step-by-step flow:

api:
  domain:
    domain_name: api.myapp.com

Deploy flow:

  1. Run deployless deploy — deployless requests an ACM certificate and shows the DNS validation records:

    [deployless] ACM certificate requested. Add these DNS records at your provider:

      CNAME  _acme.api.myapp.com  →  xxx.acm-validations.aws

    Then run 'deployless deploy' again.

  2. Add the CNAME record at your DNS provider (e.g. Cloudflare).

  3. Run deployless deploy again — deployless verifies the certificate is validated, saves the certificate_arn to deployless.yaml, and completes the deploy.

  4. After deploy, add the final CNAME to point your domain to API Gateway:

    CNAME  api.myapp.com  →  d-abc123.execute-api.us-east-1.amazonaws.com

Cost: $0 — ACM public certificates are free.

Option 3: Existing certificate​

If you already have an ACM certificate:

api:
  domain:
    domain_name: api.myapp.com
    certificate_arn: "arn:aws:acm:us-east-1:123456789:certificate/abc-123"
    base_path: /v1                    # Optional
    route53:                          # Optional — auto-configure DNS
      hosted_zone_id: Z1234567890ABC
note

EDGE endpoints require the ACM certificate to be in us-east-1. REGIONAL endpoints require the certificate to be in the same region as the API Gateway.

URL changes with custom domains​

When using a custom domain, the stage prefix is removed from the URL:

# Without custom domain (stage prefix required)
https://xxx.execute-api.us-east-1.amazonaws.com/dev/todos

# With custom domain (no stage prefix)
https://api.myapp.com/todos

Update your frontend API base URL accordingly. If you use the wrong URL (e.g. /dev/todos on a custom domain), API Gateway returns "Missing Authentication Token" without CORS headers, causing preflight failures.