Custom Domains

June 1, 2026 · View on GitHub

AppSync supports associating your API to a custom domain.

The configuration for custom domain can be found under the appSync.domain attribute.

Quick start

appSync:
  name: my-api
  domain:
    name: api.example.com
    hostedZoneId: Z111111QQQQQQQ

Configuration

  • name: Required. The fully qualified domain name to associate this API to.
  • certificateArn: Optional. A valid certificate ARN for the domain name. The certificate must be located in the us-east-1 region. See Certificate.
  • useCloudFormation: Boolean. Optional. Whether to use CloudFormation or CLI commands to manage the domain. See Using CloudFormation or CLI commands. Defaults to true.
  • retain: Boolean, optional. Whether to retain the domain and domain association when they are removed from CloudFormation. Defaults to false. See Ejecting from CloudFormation
  • hostedZoneId: Boolean, conditional. The Route53 hosted zone id where to create the certificate validation and/or AppSync Alias records. Required if useCloudFormation is true and certificateArn is not provided.
  • hostedZoneName: The hosted zone name where to create the route53 Alias record. If certificateArn is provided, it takes precedence over hostedZoneName.
  • route53: Boolean. Wether to create the Route53 Alias record for this domain. Set to false if you don't use Route53. Defaults to true.

Certificate

⚠️ AppSync serves custom domains through a CloudFront distribution. Because of this, the ACM certificate attached to the domain must be located in the us-east-1 region, no matter which region your API and CloudFormation stack are deployed to. This is an AWS requirement: AppSync rejects certificates from any other region with an error such as Certificate must be in us-east-1. This applies both to a certificate you provide via certificateArn and to one auto-generated by this plugin (see below).

If useCloudFormation is true and a valid certificateArn is not provided, a certificate will be created for the provided domain name using CloudFormation. You must provide the hostedZoneId where the DNS validation records for the certificate will be created.

⚠️ CloudFormation can only create resources in the region of the stack. As a result, the auto-generated certificate is only usable by AppSync when the stack itself is deployed to us-east-1. If your API is deployed to any other region, the certificate will be created in that region, and the deployment will fail with the Certificate must be in us-east-1 error above. In that case, create (or import) a certificate in us-east-1 yourself and reference it with certificateArn instead.

⚠️ Any change that requires a change of certificate attached to the domain requires a replacement of the AppSync domain resource. CloudFormation will usually fail with the following error when that happens:

CloudFormation cannot update a stack when a custom-named resource requires replacing. Rename api.example.com and update the stack again.

If useCloudFormation is false, when creating the domain with the domain create command, this plugin will try to find an existing certificate that matches the given domain. If no valid certificate is found, an error will be thrown. No certificate will be auto-generated.

Using CloudFormation vs the CLI commands

There are two ways to manage your custom domain:

  • using CloudFormation (default)
  • using the CLI commands

If useCloudFormation is set to true, the domain, domain association, and optionally, the domain certificate will be automatically created and managed by CloudFormation. However, in some cases you might not want that.

For example, if you want to use blue/green deployments, you might need to associate APIs from different stacks to the same domain. In that case, the only way to do it is to use the CLI.

For more information about managing domains with the CLI, see the Commands section.

⚠️ The CLI commands resolve values themselves rather than through CloudFormation, so certificateArn must be a literal ARN string when using them. CloudFormation intrinsic functions (e.g. Fn::ImportValue) are only resolved when the domain is managed by CloudFormation (useCloudFormation: true).

Ejecting from CloudFormation

If you started to manage your domain through CloudFormation and want to eject from it, follow the following steps:

  1. Set retain to true

To avoid breaking your API if it is already on production, you first need to tell CloudFormation to retain the domain and any association with an existing API. For that, you can set the retain attribute to true. You will then need to re-deploy to make sure that CloudFormation takes the change into account.

  1. Set useCloudFormation to false

You can now set useCloudFormation to false and deploy one more time. The domain and domain association resources will be removed from the CloudFormation template, but the resources will be retained (see point 1.)

  1. Manage your domain using the CLI

You can now manage your domain using the CLI commands

Domain names per stage

You can use different domains by stage easily thanks to Serverless Framework Stage Parameters

params:
  prod:
    domain: api.example.com
    domainCert: arn:aws:acm:us-east-1:123456789012:certificate/7e14a3b2-f7a5-4da5-8150-4a03ede7158c

  staging:
    domain: qa.example.com
    domainCert: arn:aws:acm:us-east-1:123456789012:certificate/61d7d798-d656-4630-9ff9-d77a7d616dbe

  default:
    domain: ${sls:stage}.example.com
    domainCert: arn:aws:acm:us-east-1:123456789012:certificate/44211071-e102-4bf4-b7b0-06d0b78cd667

appSync:
  name: my-api
  domain:
    name: ${param:domain}
    certificateArn: ${param:domainCert}