domain_names

Creates, updates, deletes, gets or lists a domain_names resource.

Overview

Name	domain_names
Type	Resource
Id	aws.apigateway.domain_names

Fields

The following fields are returned by SELECT queries:

get_domain_name

Name	Datatype	Description
certificate_arn	string	The reference to an Amazon Web Services-managed certificate that will be used by edge-optimized endpoint or private endpoint for this domain name. Certificate Manager is the only supported source.
certificate_name	string	The name of the certificate that will be used by edge-optimized endpoint or private endpoint for this domain name.
certificate_upload_date	string (date-time)	The timestamp when the certificate that was used by edge-optimized endpoint or private endpoint for this domain name was uploaded.
distribution_domain_name	string	The domain name of the Amazon CloudFront distribution associated with this custom domain name for an edge-optimized endpoint. You set up this association when adding a DNS record pointing the custom domain name to this distribution name. For more information about CloudFront distributions, see the Amazon CloudFront documentation.
distribution_hosted_zone_id	string	The region-agnostic Amazon Route 53 Hosted Zone ID of the edge-optimized endpoint. The valid value is Z2FDTNDATAQYW2 for all the regions. For more information, see Set up a Regional Custom Domain Name and AWS Regions and Endpoints for API Gateway.
domain_name	string	The custom domain name as an API host name, for example, my-api.example.com.
domain_name_arn	string	The ARN of the domain name.
domain_name_id	string	The identifier for the domain name resource. Supported only for private custom domain names.
domain_name_status	string	The status of the DomainName migration. The valid values are AVAILABLE and UPDATING. If the status is UPDATING, the domain cannot be modified further until the existing operation is complete. If it is AVAILABLE, the domain can be updated. (AVAILABLE, UPDATING, PENDING, PENDING_CERTIFICATE_REIMPORT, PENDING_OWNERSHIP_VERIFICATION, FAILED)
domain_name_status_message	string	An optional text message containing detailed information about status of the DomainName migration.
endpoint_access_mode	string	The endpoint access mode of the DomainName. (BASIC, STRICT)
endpoint_configuration	object	The endpoint configuration to indicate the types of endpoints an API (RestApi) or its custom domain name (DomainName) has and the IP address types that can invoke it.
management_policy	string	A stringified JSON policy document that applies to the API Gateway Management service for this DomainName. This policy document controls access for access association sources to create domain name access associations with this DomainName. Supported only for private custom domain names.
mutual_tls_authentication	object	The mutual TLS authentication configuration for a custom domain name. If specified, API Gateway performs two-way authentication between the client and the server. Clients must present a trusted certificate to access your API.
ownership_verification_certificate_arn	string	The ARN of the public certificate issued by ACM to validate ownership of your custom domain. Only required when configuring mutual TLS and using an ACM imported or private CA certificate ARN as the regionalCertificateArn.
policy	string	A stringified JSON policy document that applies to the execute-api service for this DomainName regardless of the caller and Method configuration. Supported only for private custom domain names.
regional_certificate_arn	string	The reference to an Amazon Web Services-managed certificate that will be used for validating the regional domain name. Certificate Manager is the only supported source.
regional_certificate_name	string	The name of the certificate that will be used for validating the regional domain name.
regional_domain_name	string	The domain name associated with the regional endpoint for this custom domain name. You set up this association by adding a DNS record that points the custom domain name to this regional domain name. The regional domain name is returned by API Gateway when you create a regional endpoint.
regional_hosted_zone_id	string	The region-specific Amazon Route 53 Hosted Zone ID of the regional endpoint. For more information, see Set up a Regional Custom Domain Name and AWS Regions and Endpoints for API Gateway.
routing_mode	string	The routing mode for this domain name. The routing mode determines how API Gateway sends traffic from your custom domain name to your private APIs. (BASE_PATH_MAPPING_ONLY, ROUTING_RULE_ONLY, ROUTING_RULE_THEN_BASE_PATH_MAPPING)
security_policy	string	The Transport Layer Security (TLS) version + cipher suite for this DomainName. (TLS_1_0, TLS_1_2, SecurityPolicy_TLS13_1_3_2025_09, SecurityPolicy_TLS13_1_3_FIPS_2025_09, SecurityPolicy_TLS13_1_2_PFS_PQ_2025_09, SecurityPolicy_TLS13_1_2_FIPS_PQ_2025_09, SecurityPolicy_TLS13_1_2_FIPS_PFS_PQ_2025_09, SecurityPolicy_TLS13_1_2_PQ_2025_09, SecurityPolicy_TLS13_1_2_2021_06, SecurityPolicy_TLS13_2025_EDGE, SecurityPolicy_TLS12_PFS_2025_EDGE, SecurityPolicy_TLS12_2018_EDGE)
tags	object	The collection of tags. Each tag element is associated with a given resource.

get_domain_names

Name	Datatype	Description
certificate_arn	string	The reference to an Amazon Web Services-managed certificate that will be used by edge-optimized endpoint or private endpoint for this domain name. Certificate Manager is the only supported source.
certificate_name	string	The name of the certificate that will be used by edge-optimized endpoint or private endpoint for this domain name.
certificate_upload_date	string (date-time)	The timestamp when the certificate that was used by edge-optimized endpoint or private endpoint for this domain name was uploaded.
distribution_domain_name	string	The domain name of the Amazon CloudFront distribution associated with this custom domain name for an edge-optimized endpoint. You set up this association when adding a DNS record pointing the custom domain name to this distribution name. For more information about CloudFront distributions, see the Amazon CloudFront documentation.
distribution_hosted_zone_id	string	The region-agnostic Amazon Route 53 Hosted Zone ID of the edge-optimized endpoint. The valid value is Z2FDTNDATAQYW2 for all the regions. For more information, see Set up a Regional Custom Domain Name and AWS Regions and Endpoints for API Gateway.
domain_name	string	The custom domain name as an API host name, for example, my-api.example.com.
domain_name_arn	string	The ARN of the domain name.
domain_name_id	string	The identifier for the domain name resource. Supported only for private custom domain names.
domain_name_status	string	The status of the DomainName migration. The valid values are AVAILABLE and UPDATING. If the status is UPDATING, the domain cannot be modified further until the existing operation is complete. If it is AVAILABLE, the domain can be updated. (AVAILABLE, UPDATING, PENDING, PENDING_CERTIFICATE_REIMPORT, PENDING_OWNERSHIP_VERIFICATION, FAILED)
domain_name_status_message	string	An optional text message containing detailed information about status of the DomainName migration.
endpoint_access_mode	string	The endpoint access mode of the DomainName. (BASIC, STRICT)
endpoint_configuration	object	The endpoint configuration to indicate the types of endpoints an API (RestApi) or its custom domain name (DomainName) has and the IP address types that can invoke it.
management_policy	string	A stringified JSON policy document that applies to the API Gateway Management service for this DomainName. This policy document controls access for access association sources to create domain name access associations with this DomainName. Supported only for private custom domain names.
mutual_tls_authentication	object	The mutual TLS authentication configuration for a custom domain name. If specified, API Gateway performs two-way authentication between the client and the server. Clients must present a trusted certificate to access your API.
ownership_verification_certificate_arn	string	The ARN of the public certificate issued by ACM to validate ownership of your custom domain. Only required when configuring mutual TLS and using an ACM imported or private CA certificate ARN as the regionalCertificateArn.
policy	string	A stringified JSON policy document that applies to the execute-api service for this DomainName regardless of the caller and Method configuration. Supported only for private custom domain names.
regional_certificate_arn	string	The reference to an Amazon Web Services-managed certificate that will be used for validating the regional domain name. Certificate Manager is the only supported source.
regional_certificate_name	string	The name of the certificate that will be used for validating the regional domain name.
regional_domain_name	string	The domain name associated with the regional endpoint for this custom domain name. You set up this association by adding a DNS record that points the custom domain name to this regional domain name. The regional domain name is returned by API Gateway when you create a regional endpoint.
regional_hosted_zone_id	string	The region-specific Amazon Route 53 Hosted Zone ID of the regional endpoint. For more information, see Set up a Regional Custom Domain Name and AWS Regions and Endpoints for API Gateway.
routing_mode	string	The routing mode for this domain name. The routing mode determines how API Gateway sends traffic from your custom domain name to your private APIs. (BASE_PATH_MAPPING_ONLY, ROUTING_RULE_ONLY, ROUTING_RULE_THEN_BASE_PATH_MAPPING)
security_policy	string	The Transport Layer Security (TLS) version + cipher suite for this DomainName. (TLS_1_0, TLS_1_2, SecurityPolicy_TLS13_1_3_2025_09, SecurityPolicy_TLS13_1_3_FIPS_2025_09, SecurityPolicy_TLS13_1_2_PFS_PQ_2025_09, SecurityPolicy_TLS13_1_2_FIPS_PQ_2025_09, SecurityPolicy_TLS13_1_2_FIPS_PFS_PQ_2025_09, SecurityPolicy_TLS13_1_2_PQ_2025_09, SecurityPolicy_TLS13_1_2_2021_06, SecurityPolicy_TLS13_2025_EDGE, SecurityPolicy_TLS12_PFS_2025_EDGE, SecurityPolicy_TLS12_2018_EDGE)
tags	object	The collection of tags. Each tag element is associated with a given resource.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_domain_name	select	domain_name, region	domainNameId	Represents a domain name that is contained in a simpler, more intuitive URL that can be called.
get_domain_names	select	region	position, limit, resourceOwner	Represents a collection of DomainName resources.
create_domain_name	insert	region, domainName		Creates a new domain name.
update_domain_name	update	domain_name, region	domainNameId	Changes information about the DomainName resource.
delete_domain_name	delete	domain_name, region	domainNameId	Deletes the DomainName resource.
reject_domain_name_access_association	exec	domainNameAccessAssociationArn, domainNameArn, region		Rejects a domain name access association with a private custom domain name. To reject a domain name access association with an access association source in another AWS account, use this operation. To remove a domain name access association with an access association source in your own account, use the DeleteDomainNameAccessAssociation operation.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
domainNameAccessAssociationArn	string	The ARN of the domain name access association resource.
domainNameArn	string	The ARN of the domain name.
domain_name	string	The name of the DomainName resource to be deleted.
region	string	AWS region (default: us-east-1)
domainNameId	string	The identifier for the domain name resource. Supported only for private custom domain names.
limit	integer	The maximum number of returned results per page. The default value is 25 and the maximum value is 500.
position	string	The current pagination position in the paged result set.
resourceOwner	string	The owner of the domain name access association.

SELECT examples

get_domain_name

Represents a domain name that is contained in a simpler, more intuitive URL that can be called.

SELECT
certificate_arn,
certificate_name,
certificate_upload_date,
distribution_domain_name,
distribution_hosted_zone_id,
domain_name,
domain_name_arn,
domain_name_id,
domain_name_status,
domain_name_status_message,
endpoint_access_mode,
endpoint_configuration,
management_policy,
mutual_tls_authentication,
ownership_verification_certificate_arn,
policy,
regional_certificate_arn,
regional_certificate_name,
regional_domain_name,
regional_hosted_zone_id,
routing_mode,
security_policy,
tags
FROM aws.apigateway.domain_names
WHERE domain_name = '{{ domain_name }}' -- required
AND region = '{{ region }}' -- required
AND domainNameId = '{{ domainNameId }}'
;

get_domain_names

Represents a collection of DomainName resources.

SELECT
certificate_arn,
certificate_name,
certificate_upload_date,
distribution_domain_name,
distribution_hosted_zone_id,
domain_name,
domain_name_arn,
domain_name_id,
domain_name_status,
domain_name_status_message,
endpoint_access_mode,
endpoint_configuration,
management_policy,
mutual_tls_authentication,
ownership_verification_certificate_arn,
policy,
regional_certificate_arn,
regional_certificate_name,
regional_domain_name,
regional_hosted_zone_id,
routing_mode,
security_policy,
tags
FROM aws.apigateway.domain_names
WHERE region = '{{ region }}' -- required
AND position = '{{ position }}'
AND limit = '{{ limit }}'
AND resourceOwner = '{{ resourceOwner }}'
;

INSERT examples

create_domain_name

Creates a new domain name.

INSERT INTO aws.apigateway.domain_names (
domainName,
certificateName,
certificateBody,
certificatePrivateKey,
certificateChain,
certificateArn,
regionalCertificateName,
regionalCertificateArn,
endpointConfiguration,
tags,
securityPolicy,
endpointAccessMode,
mutualTlsAuthentication,
ownershipVerificationCertificateArn,
policy,
routingMode,
region
)
SELECT 
'{{ domainName }}' /* required */,
'{{ certificateName }}',
'{{ certificateBody }}',
'{{ certificatePrivateKey }}',
'{{ certificateChain }}',
'{{ certificateArn }}',
'{{ regionalCertificateName }}',
'{{ regionalCertificateArn }}',
'{{ endpointConfiguration }}',
'{{ tags }}',
'{{ securityPolicy }}',
'{{ endpointAccessMode }}',
'{{ mutualTlsAuthentication }}',
'{{ ownershipVerificationCertificateArn }}',
'{{ policy }}',
'{{ routingMode }}',
'{{ region }}'
RETURNING
certificate_arn,
certificate_name,
certificate_upload_date,
distribution_domain_name,
distribution_hosted_zone_id,
domain_name,
domain_name_arn,
domain_name_id,
domain_name_status,
domain_name_status_message,
endpoint_access_mode,
endpoint_configuration,
management_policy,
mutual_tls_authentication,
ownership_verification_certificate_arn,
policy,
regional_certificate_arn,
regional_certificate_name,
regional_domain_name,
regional_hosted_zone_id,
routing_mode,
security_policy,
tags
;

Manifest

# Description fields are for documentation purposes
- name: domain_names
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the domain_names resource.
  - name: domainName
    value: "{{ domainName }}"
  - name: certificateName
    value: "{{ certificateName }}"
  - name: certificateBody
    value: "{{ certificateBody }}"
  - name: certificatePrivateKey
    value: "{{ certificatePrivateKey }}"
  - name: certificateChain
    value: "{{ certificateChain }}"
  - name: certificateArn
    value: "{{ certificateArn }}"
  - name: regionalCertificateName
    value: "{{ regionalCertificateName }}"
  - name: regionalCertificateArn
    value: "{{ regionalCertificateArn }}"
  - name: endpointConfiguration
    description: |
      The endpoint configuration to indicate the types of endpoints an API (RestApi) or its custom domain name (DomainName) has and the IP address types that can invoke it.
    value:
      types:
        - "{{ types }}"
      ipAddressType: "{{ ipAddressType }}"
      vpcEndpointIds:
        - "{{ vpcEndpointIds }}"
  - name: tags
    value: "{{ tags }}"
  - name: securityPolicy
    value: "{{ securityPolicy }}"
    valid_values: ['TLS_1_0', 'TLS_1_2', 'SecurityPolicy_TLS13_1_3_2025_09', 'SecurityPolicy_TLS13_1_3_FIPS_2025_09', 'SecurityPolicy_TLS13_1_2_PFS_PQ_2025_09', 'SecurityPolicy_TLS13_1_2_FIPS_PQ_2025_09', 'SecurityPolicy_TLS13_1_2_FIPS_PFS_PQ_2025_09', 'SecurityPolicy_TLS13_1_2_PQ_2025_09', 'SecurityPolicy_TLS13_1_2_2021_06', 'SecurityPolicy_TLS13_2025_EDGE', 'SecurityPolicy_TLS12_PFS_2025_EDGE', 'SecurityPolicy_TLS12_2018_EDGE']
  - name: endpointAccessMode
    value: "{{ endpointAccessMode }}"
    valid_values: ['BASIC', 'STRICT']
  - name: mutualTlsAuthentication
    description: |
      The mutual TLS authentication configuration for a custom domain name. If specified, API Gateway performs two-way authentication between the client and the server. Clients must present a trusted certificate to access your API.
    value:
      truststoreUri: "{{ truststoreUri }}"
      truststoreVersion: "{{ truststoreVersion }}"
  - name: ownershipVerificationCertificateArn
    value: "{{ ownershipVerificationCertificateArn }}"
  - name: policy
    value: "{{ policy }}"
  - name: routingMode
    value: "{{ routingMode }}"
    valid_values: ['BASE_PATH_MAPPING_ONLY', 'ROUTING_RULE_ONLY', 'ROUTING_RULE_THEN_BASE_PATH_MAPPING']

UPDATE examples

update_domain_name

Changes information about the DomainName resource.

UPDATE aws.apigateway.domain_names
SET 
patchOperations = '{{ patchOperations }}'
WHERE 
domain_name = '{{ domain_name }}' --required
AND region = '{{ region }}' --required
AND domainNameId = '{{ domainNameId}}'
RETURNING
certificate_arn,
certificate_name,
certificate_upload_date,
distribution_domain_name,
distribution_hosted_zone_id,
domain_name,
domain_name_arn,
domain_name_id,
domain_name_status,
domain_name_status_message,
endpoint_access_mode,
endpoint_configuration,
management_policy,
mutual_tls_authentication,
ownership_verification_certificate_arn,
policy,
regional_certificate_arn,
regional_certificate_name,
regional_domain_name,
regional_hosted_zone_id,
routing_mode,
security_policy,
tags;

DELETE examples

delete_domain_name

Deletes the DomainName resource.

DELETE FROM aws.apigateway.domain_names
WHERE domain_name = '{{ domain_name }}' --required
AND region = '{{ region }}' --required
AND domainNameId = '{{ domainNameId }}'
;

Lifecycle Methods

reject_domain_name_access_association

Rejects a domain name access association with a private custom domain name. To reject a domain name access association with an access association source in another AWS account, use this operation. To remove a domain name access association with an access association source in your own account, use the DeleteDomainNameAccessAssociation operation.

EXEC aws.apigateway.domain_names.reject_domain_name_access_association 
@domainNameAccessAssociationArn='{{ domainNameAccessAssociationArn }}' --required, 
@domainNameArn='{{ domainNameArn }}' --required, 
@region='{{ region }}' --required
;