# Private REST APIs in API Gateway Private REST APIs A private API is a REST API that is only callable from within an Amazon VPC. You can access your API using an [interface VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html), which is an endpoint network interface that you create in your VPC. Interface endpoints are powered by AWS PrivateLink, a technology that enables you to privately access AWS services by using private IP addresses. You can also use Direct Connect to establish a connection from an on-premises network to Amazon VPC and then access your private API over that connection. In all cases, traffic to your private API uses secure connections and is isolated from the public internet. Traffic doesn't leave the Amazon network. ## Best practices for private APIs We recommend that you use the following best practices when you create your private API: + Use a single VPC endpoint to access multiple private APIs. This reduces the number of VPC endpoints that you might need. + Associate your VPC endpoint to your API. This creates a Route 53 alias DNS record and simplifies invoking your private API. + Turn on private DNS for your VPC. When you turn on private DNS for your VPC, you can invoke your API within a VPC without passing the `Host` or `x-apigw-api-id` header. If you turn on private DNS, you can’t access the default endpoint for public APIs. To access the default endpoint for public APIs, you can turn off private DNS, create a private hosted zone for each private API in your VPC, and then provision the required records in Route 53. This allows your private API to resolve while you can still invoke public default endpoint from your VPC. For more information, see [Creating a private hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html). + Restrict access to your private API to specific VPCs or VPC endpoints. Add `aws:SourceVpc` or `aws:SourceVpce` conditions to your API's resource policy to restrict access. + For the most secure data perimeter, you can create a VPC endpoint policy. This controls access to the VPC endpoints that can invoke your private API. ## Considerations for private APIs The following considerations might impact your use of private APIs: + Only REST APIs are supported. + You cannot convert a private API to an edge-optimized API. + Private APIs only support TLS 1.2. Earlier TLS versions are not supported. + If you make a request using HTTP/2 protocol, the request is enforced to use HTTP/1.1 protocol. + You can't set the IP address type for private APIs to only allow IPv4 addresses to invoke your private API. Only dualstack is supported. For more information, see [IP address types for REST APIs in API Gateway](api-gateway-ip-address-type.md). + To send traffic using your private API, you can use all IP address types supported by Amazon VPC. You can send dualstack and IPv6 traffic by configuring the settings on your VPC endpoint. You can't modify this using API Gateway. For more information, see [Add IPv6 support for your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6-add.html). + VPC endpoints for private APIs are subject to the same limitations as other interface VPC endpoints. For more information, see [Access an AWS service using an interface VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html) in the *AWS PrivateLink Guide*. For more information about using API Gateway with shared VPCs and shared subnets, see [Shared subnets](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#interface-endpoint-shared-subnets) in the *AWS PrivateLink Guide*. ## Next steps for private APIs To learn how to create a private API and associate a VPC endpoint see, [Create a private API](apigateway-private-api-create.md). To follow a tutorial where you create dependencies in CloudFormation and a private API in the AWS Management Console, see [Tutorial: Create a private REST API](private-api-tutorial.md). # Create a private API Before you create a private API, you first create a VPC endpoint for API Gateway. Next you create your private API and attach a resource policy to it. Optionally, you can associate your VPC endpoint with your private API to simplify how you invoke your API. Finally, you deploy your API. The following procedures describe how to accomplish this. You can create a private REST API using the AWS Management Console, AWS CLI or an AWS SDK. ## Prerequisites To follow these steps, you must have a fully configured VPC. To learn how to create a VPC, see [Create a VPC only](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html#create-vpc-only) in the *Amazon VPC User Guide*. To follow all recommend steps when you create your VPC, enable private DNS. This way you can invoke your API within a VPC without having to pass the Host or `x-apigw-api-id` header. To enable private DNS, the `enableDnsSupport` and `enableDnsHostnames` attributes of your VPC must be set to `true`. For more information, see [DNS Support in Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-support) and [Updating DNS Support for Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-updating). ## Step 1: Create a VPC endpoint for API Gateway in your VPC The following procedure shows how to create a VPC endpoint for API Gateway. To create a VPC endpoint for API Gateway, you specify the `execute-api` domain for the AWS Region where you create your private API. The `execute-api` domain is the API Gateway component service for API execution. When you create your VPC endpoint for API Gateway, you specify the DNS settings. If you turn off private DNS, you can only access your API using public DNS. For more information, see [Issue: I can't connect to my public API from an API Gateway VPC endpoint](#apigateway-private-api-troubleshooting-public-access). ------ #### [ AWS Management Console ] **To create an interface VPC endpoint for API Gateway** 1. Sign in to the AWS Management Console and open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/). 1. In the navigation pane, under **Virtual private cloud**, choose **Endpoints**. 1. Choose **Create endpoint**. 1. (Optional) For **Name tag**, enter a name to help identify your VPC endpoint. 1. For **Service category**, choose **AWS services**. 1. Under **Services**, in the search bar, enter **execute-api**. Then, choose the API Gateway service endpoint in the AWS Region where you will create your API. The service name should look like `com.amazonaws.us-east-1.execute-api` and the **Type** should be **Interface**. 1. For **VPC**, choose the VPC that you want to create the endpoint in. 1. (Optional) To turn off **Enable Private DNS Name**, choose **Additional settings** and then clear **Enable Private DNS Name**. 1. For **Subnets**, choose the Availability Zones where you created the endpoint network interfaces. To improve the availability of your API, choose multiple subnets. 1. For **Security group**, select the security group to associate with the VPC endpoint network interfaces. The security group you choose must be set to allow TCP Port 443 inbound HTTPS traffic from either an IP range in your VPC or another security group in your VPC. 1. For **Policy**, do one of the following: + If you have not created your private API or you don't want to configure a custom VPC endpoint policy, choose **Full access**. + If you have already created a private API and want to configure a custom VPC endpoint policy, you can enter a custom VPC endpoint policy. For more information, see [Use VPC endpoint policies for private APIs in API Gateway](apigateway-vpc-endpoint-policies.md). You can update the VPC endpoint policy after you create your VPC endpoint. For more information, see [Update a VPC endpoint policy](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html#update-vpc-endpoint-policy). 1. Choose **Create endpoint**. 1. Copy the resulting VPC endpoint ID, as you might use it in future steps. ------ #### [ AWS CLI ] The following [create-vpc-endpoint](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-vpc-endpoint.html) command creates a VPC endpoint: ``` aws ec2 create-vpc-endpoint \ --vpc-id vpc-1a2b3c4d \ --vpc-endpoint-type Interface \ --service-name com.amazonaws.us-east-1.execute-api \ --subnet-ids subnet-7b16de0c \ --security-group-id sg-1a2b3c4d ``` Copy the resulting VPC endpoint ID, as you might use it in future steps. ------ ## Step 2: Create a private API After you create your VPC endpoint, you create a private REST API. The following procedure shows how to create a private API. ------ #### [ AWS Management Console ] **To create a private API** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose **Create API**. 1. Under **REST API**, choose **Build**. 1. For **Name**, enter a name. 1. (Optional) For **Description**, enter a description. 1. For **API endpoint type**, select **Private**. 1. (Optional) For **VPC endpoint IDs**, enter a VPC endpoint ID. If you associate a VPC endpoint ID with your private API, you can invoke your API from within your VPC without overriding a `Host` header or passing an `x-apigw-api-id header` For more information, see [(Optional) Associate or disassociate a VPC endpoint with a private API](#associate-private-api-with-vpc-endpoint). 1. For **IP address type**, choose **Dualstack**. 1. Choose **Create API**. After completing the preceding steps, you can follow the instructions in [Get started with the REST API console](getting-started-rest-new-console.md) to set up methods and integrations for this API, but you can't deploy your API. To deploy your API, follow step 3 and attach a resource policy to your API. ------ #### [ AWS CLI ] The following [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) command creates a private API: ``` aws apigateway create-rest-api \ --name 'Simple PetStore (AWS CLI, Private)' \ --description 'Simple private PetStore API' \ --region us-west-2 \ --endpoint-configuration '{ "types": ["PRIVATE"], "ipAddressType": "dualstack" }' ``` A successful call returns output similar to the following: ``` { "createdDate": "2017-10-13T18:41:39Z", "description": "Simple private PetStore API", "endpointConfiguration": { "types": [ "PRIVATE" ], "ipAddressType": "dualstack" }, "id": "0qzs2sy7bh", "name": "Simple PetStore (AWS CLI, Private)" } ``` After completing the preceding steps, you can follow the instructions in [Tutorial: Create a REST API using AWS SDKs or the AWS CLI](api-gateway-create-api-cli-sdk.md) to set up methods and integrations for this API, but you can't deploy your API. To deploy your API, follow step 3 and attach a resource policy to your API. ------ #### [ SDK JavaScript v3 ] The following example shows how to create a private API by using the AWS SDK for JavaScript v3: ``` import {APIGatewayClient, CreateRestApiCommand} from "@aws-sdk/client-api-gateway"; const apig = new APIGatewayClient({region:"us-east-1"}); const input = { // CreateRestApiRequest name: "Simple PetStore (JavaScript v3 SDK, private)", // required description: "Demo private API created using the AWS SDK for JavaScript v3", version: "0.00.001", endpointConfiguration: { // EndpointConfiguration types: [ "PRIVATE"], }, }; export const handler = async (event) => { const command = new CreateRestApiCommand(input); try { const result = await apig.send(command); console.log(result); } catch (err){ console.error(err) } }; ``` A successful call returns output similar to the following: ``` { apiKeySource: 'HEADER', createdDate: 2024-04-03T17:56:36.000Z, description: 'Demo private API created using the AWS SDK for JavaScript v3', disableExecuteApiEndpoint: false, endpointConfiguration: { types: [ 'PRIVATE' ] }, id: 'abcd1234', name: 'Simple PetStore (JavaScript v3 SDK, private)', rootResourceId: 'efg567', version: '0.00.001' } ``` After completing the preceding steps, you can follow the instructions in [Tutorial: Create a REST API using AWS SDKs or the AWS CLI](api-gateway-create-api-cli-sdk.md) to set up methods and integrations for this API, but you can't deploy your API. To deploy your API, follow step 3 and attach a resource policy to your API. ------ #### [ Python SDK ] The following example shows how to create a private API by using the AWS SDK for Python: ``` import json import boto3 import logging logger = logging.getLogger() apig = boto3.client('apigateway') def lambda_handler(event, context): try: result = apig.create_rest_api( name='Simple PetStore (Python SDK, private)', description='Demo private API created using the AWS SDK for Python', version='0.00.001', endpointConfiguration={ 'types': [ 'PRIVATE', ], }, ) except botocore.exceptions.ClientError as error: logger.exception("Couldn't create private API %s.", error) raise attribute=["id", "name", "description", "createdDate", "version", "apiKeySource", "endpointConfiguration"] filtered_data ={key:result[key] for key in attribute} result = json.dumps(filtered_data, default=str, sort_keys='true') return result ``` A successful call returns output similar to the following: ``` "{\"apiKeySource\": \"HEADER\", \"createdDate\": \"2024-04-03 17:27:05+00:00\", \"description\": \"Demo private API created using the AWS SDK for \", \"endpointConfiguration\": {\"types\": [\"PRIVATE\"]}, \"id\": \"abcd1234\", \"name\": \"Simple PetStore (Python SDK, private)\", \"version\": \"0.00.001\"}" ``` After completing the preceding steps, you can follow the instructions in [Tutorial: Create a REST API using AWS SDKs or the AWS CLI](api-gateway-create-api-cli-sdk.md) to set up methods and integrations for this API, but you can't deploy your API. To deploy your API, follow step 3 and attach a resource policy to your API. ------ ## Step 3: Set up a resource policy for a private API Your current private API is inaccessible to all VPCs. Use a resource policy to grant your VPCs and VPC endpoints access to your private APIs. You can grant access to a VPC endpoint in any AWS account. Your resource policy should contain `aws:SourceVpc` or `aws:SourceVpce` conditions to restrict access. We recommend that you identify specific VPCs and VPC endpoints and don't create a resource policy that allows access for all VPCs and VPC endpoints. The following procedure shows how to attach a resource policy to your API. ------ #### [ AWS Management Console ] 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose a REST API. 1. In the main navigation pane, choose **Resource policy**. 1. Choose **Create policy**. 1. Choose **Select a template** and then choose **Source VPC**. 1. Replace `{{vpcID}}` (including the curly braces) with your VPC ID. 1. Choose **Save changes**. ------ #### [ AWS CLI ] The following [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) command attaches a resource policy to an existing API: ``` aws apigateway update-rest-api \ --rest-api-id a1b2c3 \ --patch-operations op=replace,path=/policy,value='"{\"jsonEscapedPolicyDocument\"}"' ``` ------ You might also want to control which resources have access to your VPC endpoint. To control which resources have access to your VPC endpoint, attach an endpoint policy to your VPC endpoint. For more information, see [Use VPC endpoint policies for private APIs in API Gateway](apigateway-vpc-endpoint-policies.md). ## (Optional) Associate or disassociate a VPC endpoint with a private API When you associate a VPC endpoint with your private API, API Gateway generates a new Route 53 alias DNS record. You can use this record to invoke your private APIs just as you do your public APIs without overriding a `Host` header or passing an `x-apigw-api-id` header. The generated base URL is in the following format: ``` https://{rest-api-id}-{vpce-id}.execute-api.{region}.amazonaws.com/{stage} ``` ------ #### [ Associate a VPC endpoint (AWS Management Console) ] You can associate a VPC endpoint with your private API when you create it, or after it's created. The following procedure shows how to associate a VPC endpoint with a previously created API. **To associate a VPC endpoint with a private API** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose your private API. 1. In the main navigation pane, choose **Resource policy**. 1. Edit your resource policy to allow calls from your additional VPC endpoint. 1. In the main navigation pane, choose **API settings**. 1. In the **API details** section, choose **Edit**. 1. For **VPC endpoint IDs**, select additional VPC endpoint IDs. 1. Choose **Save**. 1. Redeploy your API for the changes to take effect. ------ #### [ Dissociate a VPC endpoint (AWS Management Console) ] **To disassociate a VPC endpoint from a private REST API** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose your private API. 1. In the main navigation pane, choose **Resource policy**. 1. Edit your resource policy to remove mentions of the VPC endpoint you want to dissociate from your private API. 1. In the main navigation pane, choose **API settings**. 1. In the **API details** section, choose **Edit**. 1. For **VPC endpoint IDs**, choose the **X** to dissociate the VPC endpoint. 1. Choose **Save**. 1. Redeploy your API for the changes to take effect. ------ #### [ Associate a VPC endpoint (AWS CLI) ] The following [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) command associates VPC endpoints at the time of API creation: ``` aws apigateway create-rest-api \ --name Petstore \ --endpoint-configuration '{ "types": ["PRIVATE"], "vpcEndpointIds" : ["vpce-0212a4ababd5b8c3e", "vpce-0393a628149c867ee"] }' \ --region us-west-2 ``` The output will look like the following: ``` { "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "PRIVATE" ], "vpcEndpointIds": [ "vpce-0212a4ababd5b8c3e", "vpce-0393a628149c867ee" ] }, "id": "u67n3ov968", "createdDate": 1565718256, "name": "Petstore" } ``` The following [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) command associates VPC endpoints to an API that you already created: ``` aws apigateway update-rest-api \ --rest-api-id u67n3ov968 \ --patch-operations "op='add',path='/endpointConfiguration/vpcEndpointIds',value='vpce-01d622316a7df47f9'" \ --region us-west-2 ``` The output will look like the following: ``` { "name": "Petstore", "apiKeySource": "1565718256", "tags": {}, "createdDate": 1565718256, "endpointConfiguration": { "vpcEndpointIds": [ "vpce-0212a4ababd5b8c3e", "vpce-0393a628149c867ee", "vpce-01d622316a7df47f9" ], "types": [ "PRIVATE" ] }, "id": "u67n3ov968" } ``` Redeploy your API for the changes to take effect. ------ #### [ Disassociate a VPC endpoint (AWS CLI) ] The following [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) command dissociates a VPC endpoint from a private API: ``` aws apigateway update-rest-api \ --rest-api-id u67n3ov968 \ --patch-operations "op='remove',path='/endpointConfiguration/vpcEndpointIds',value='vpce-0393a628149c867ee'" \ --region us-west-2 ``` The output will look like the following: ``` { "name": "Petstore", "apiKeySource": "1565718256", "tags": {}, "createdDate": 1565718256, "endpointConfiguration": { "vpcEndpointIds": [ "vpce-0212a4ababd5b8c3e", "vpce-01d622316a7df47f9" ], "types": [ "PRIVATE" ] }, "id": "u67n3ov968" } ``` Redeploy your API for the changes to take effect. ------ ## Step 4: Deploy a private API To deploy your API, you create an API deployment and associate it with a stage. The following procedure shows how to deploy your private API. ------ #### [ AWS Management Console ] **To deploy a private API** 1. Choose your API. 1. Choose **Deploy API**. 1. For **Stage**, select **New stage**. 1. For **Stage name**, enter a stage name. 1. (Optional) For **Description**, enter a description. 1. Choose **Deploy**. ------ #### [ AWS CLI ] The following [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) command deploys a private API: ``` aws apigateway create-deployment --rest-api-id a1b2c3 \ --stage-name test \ --stage-description 'Private API test stage' \ --description 'First deployment' ``` ------ ## Troubleshoot your private API The following provides troubleshooting advice for errors and issues that you might encounter when creating a private API. ### Issue: I can't connect to my public API from an API Gateway VPC endpoint When you create your VPC, you can configure the DNS settings. We recommend that you turn on private DNS for your VPC. If you choose turn off private DNS, you're only able to access your API via public DNS. If you enable private DNS, you can't access the default endpoint of a public API Gateway API from your VPC endpoint. You can access an API with a custom domain name. If you create a Regional custom domain name, use an A type alias record, if you create an edge-optimized custom domain name, there are no restrictions for your record type. You can access these public APIs with private DNS enabled. For more information, see [Issue: I connect to my public API from an API Gateway VPC endpoint](https://repost.aws/knowledge-center/api-gateway-vpc-connections). ### Issue: My API returns `{"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: arn:aws:execute-api:us-east-1:********/****/****/"}` In your resource policy, if you set the Principal to an AWS principal, such as the following: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:role/developer", "arn:aws:iam::111122223333:role/Admin" ] }, "Action": "execute-api:Invoke", "Resource": [ "execute-api:/stage/GET/pets" ] } ] } ``` ------ You must use `AWS_IAM` authorization for every method in your API, or else your API returns the previous error message. For more instructions on how to turn on `AWS_IAM` authorization for a method, see [Methods for REST APIs in API Gateway](how-to-method-settings.md). ### Issue: I can't tell if my VPC endpoint is associated with my API If you associate or dissociate a VPC endpoint with your private API, you need to redeploy your API. The update operation might take few minutes to complete due to DNS propagation. During this time, your API is available, but DNS propagation for the newly generated DNS URLs may still be in progress. If after several minutes, your new URLs are not resolving in DNS, we recommend that you redeploy your API. # Custom domain names for private APIs in API Gateway Custom domain names for private APIs You can create a custom domain name for your private APIs. Use a private custom domain name to provide API callers with a simpler and more intuitive URL. With a private custom domain name, you can reduce complexity, configure security measures during the TLS handshake, and control the certificate lifecycle of your domain name using AWS Certificate Manager (ACM). For more information, see [Securing your certificate's private key for your custom domain name](#apigateway-private-custom-domains-secure-certificate-private-key). Custom domain names for private APIs don’t need to be unique across multiple accounts. You can create `example.private.com` in account 111122223333 and in account 555555555555, as long as your ACM certificate covers the domain name. To identify a private custom domain name, use the private custom domain name ARN. This identifier is unique to private custom domain names. When you create a private custom domain name in API Gateway, you're an *API provider*. You can provide your private custom domain name to other AWS accounts using API Gateway or AWS Resource Access Manager (AWS RAM). When you invoke a private custom domain name, you're an *API consumer*. You can consume a private custom domain name from your own AWS account or from another AWS account. When you consume a private custom domain name, you create a domain name access association between a VPC endpoint and a private custom domain name. With a domain name access association, API consumers can invoke your private custom domain name while isolated from the public internet. For more information, see [Tasks of API providers and API consumers for custom domain names for private APIs](apigateway-private-custom-domains-associations.md). ## Securing your certificate's private key for your custom domain name When you request an SSL/TLS certificate using ACM to create your custom domain name for private APIs, ACM generates a public/private key pair. When you import a certificate, you generate the key pair. The public key becomes part of the certificate. To safely store the private key, ACM creates another key using AWS KMS, called the KMS key, with the alias **aws/acm**. AWS KMS uses this key to encrypt your certificate’s private key. For more information, see [Data protection in AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/data-protection.html) in the *AWS Certificate Manager User Guide*. API Gateway uses AWS TLS Connection Manager, a service that is only accessible to AWS services, to secure and use your certificate's private keys. When you use your ACM certificate to create a API Gateway custom domain name, API Gateway associates your certificate with AWS TLS Connection Manager. We do this by creating a grant in AWS KMS against your AWS managed key. This grant allows TLS Connection Manager to use AWS KMS to decrypt your certificate's private key. TLS Connection Manager uses the certificate and the decrypted (plaintext) private key to establish a secure connection (SSL/TLS session) with clients of API Gateway services. When the certificate is disassociated from a API Gateway service, the grant is retired. For more information, see [Grants](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in the *AWS Key Management Service Developer Guide*. For more information, see [Data encryption at rest in Amazon API Gateway](data-protection-encryption.md#data-protection-at-rest). ## Considerations for private custom domain names The following considerations might impact your use of private custom domain names: + It takes about 15 minutes for API Gateway to provision your private custom domain name. + If you update your ACM certificate, it takes about 15 minutes for API Gateway to complete the update. During this time, your domain name is in the `UPDATING` state, and you can still access it. + To invoke a private custom domain name, you must create a domain name access association. After you create a domain name access association, it takes about 15 minutes to be ready. + The private custom domain name ARN contains the *account-id* and the *domain-name-id*. When you create a domain name, API Gateway uses the ARN format of `arn:partition:apigateway:region::/domainnames/domain-name`. When you access a private custom domain name, you use the ARN format of `arn:partition:apigateway:region:account-id:/domainnames/domain-name+domain-name-id`. You might need to modify your IAM permissions to allow access to a private domain name after you create it. + You can't invoke private custom domain names with the same name from the same VPC endpoint. For example, if you wanted to invoke `arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234` and `arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+xyz000`, associate each private custom domain name with a different VPC endpoint. + Wildcard certificates are supported, such as a certificate for `*.private.example.com`. + Wildcard custom domain names aren't supported. + Only RSA certificates with a 2048-bit key length and ECDSA certificates with 256-bit and 384-bit key lengths are supported. + You can't set the IP address type for private APIs to only allow IPv4 addresses to invoke your private API. Only dualstack is supported. For more information, see [IP address types for REST APIs in API Gateway](api-gateway-ip-address-type.md). + To send traffic using your private API, you can use all IP address types supported by Amazon VPC. You can send dualstack and IPv6 traffic by configuring the settings on your VPC endpoint. You can't modify this using API Gateway. For more information, see [Add IPv6 support for your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6-add.html). + Multi-level base path mapping, such as mapping your private API to `/developers/feature`, isn't supported, but you can use a routing rule to create a multi-level path condition. For more information, see [Send traffic to your APIs through your custom domain name in API Gateway](rest-api-routing-mode.md). + You can’t set a minimum TLS version for your private custom domain name. All private custom domain names have the security policy of `TLS-1-2`. + You can use VPC endpoint policy to control access to a private custom domain name. For more information, see examples 4 and 5 in [Use VPC endpoint policies for private APIs in API Gateway](apigateway-vpc-endpoint-policies.md). + You must create a separate resource policy for your private API and for your private custom domain name. To invoke a private custom domain name, an API consumer needs access from the private custom domain name resource policy, the private API resource policy, and any VPC endpoint policies or authorization on the private API. ## Considerations for using private custom domain names with other API Gateway resources The following considerations might impact how you use private custom domain names with other API Gateway resources: + You can't send traffic from a private custom domain name to a public API. + When a private API is mapped to a private custom domain name, you can't change the API's endpoint type. + You can't migrate a public custom domain name to a private custom domain name. + If you have a VPC endpoint that you use to access a public custom domain name, don't use it to create a domain name access association with a private custom domain name. ## Differences between private custom domain names and public custom domain names The following describes the differences between private and public custom domain names: + Private custom domain names don’t need to be unique across multiple accounts. + A private domain name has a domain name ID. This ID uniquely identifies a private custom domain name and isn't generated for public custom domain names. + When you use the AWS CLI to update or delete your private custom domain name, you must provide the domain name ID. If you have a private custom domain name called `example.com` and a public custom domain name called `example.com` and you don't provide the domain name ID, API Gateway will modify or delete your public custom domain name. ## Next steps for custom domain names for private APIs For information about the tasks of an API provider and an API consumer, see [Tasks of API providers and API consumers for custom domain names for private APIs](apigateway-private-custom-domains-associations.md). For instructions on creating a private custom domain name that you can invoke in your own AWS account, see [Tutorial: Create and invoke a custom domain name for private APIs](apigateway-private-custom-domains-tutorial.md). For instructions on providing another AWS account access to your private custom domain name, see [API provider: Share your private custom domain name using AWS RAM](apigateway-private-custom-domains-provider-share.md). For instructions on associating your VPC endpoint with a private custom domain name in another AWS account, see [API consumer: Associate your VPC endpoint with a private custom domain name shared with you](apigateway-private-custom-domains-consumer-create.md). # Tasks of API providers and API consumers for custom domain names for private APIs API providers and API consumers When you create a private custom domain name, you're an *API provider*. When you invoke a private custom domain name, you're an *API consumer*. You can consume a private custom domain name from your own AWS account or from another AWS account. The following section explains the tasks required by the API provider and API consumer to use a private custom domain name. If you want to invoke a private custom domain name in your own AWS account, you are both the API provider and the API consumer. If you want to invoke a private custom domain in another AWS account, depending on the trust relationship between the API provider and API consumer in AWS Organizations, AWS RAM might complete some tasks for you. ## Tasks of an API provider API providers create private APIs and map them to custom domain names. API providers manage two resource policies to protect their private custom domain names. The first policy is for the `execute-api` service and controls which VPC endpoints can invoke your private custom domain name. In the private custom domain name configuration, it's called the `policy`. The second policy is for the Amazon API Gateway Management service and controls which VPC endpoints in other AWS accounts can form a domain name access association with your private custom domain name. A VPC endpoint needs to form a domain name access association with a private custom domain name to invoke it. In the private custom domain name configuration, it's the `managementPolicy`. You can use AWS RAM or API Gateway to update this policy. If you don't plan on allowing VPC endpoints in other AWS accounts to invoke your custom domain name, you don't edit the `managementPolicy`. If you are an API provider, you must do the following: 1. Create a private API. 1. Update your private API's `policy` to grant your VPC endpoint access to your private API. 1. Create a private custom domain name. 1. Update your private custom domain name's `policy` to grant your VPC endpoint access to your private custom domain name. 1. Create a base path mapping or a routing rule to send traffic from your private API to your private custom domain name. For more information, see [Send traffic to your APIs through your custom domain name in API Gateway](rest-api-routing-mode.md). If you want to allow API consumers in other AWS accounts to access your private custom domain name, do the following: 1. Update the `managementPolicy` of your private custom domain name to allow API consumers in other accounts to associate their VPC endpoints with your private custom domain name. You can do this using the following methods: **AWS RAM** With AWS RAM, if the API provider and the API consumer are in the same organization using AWS Organizations, the resource share between provider and consumer is automatically accepted. Otherwise, you should wait until the API consumer accepts the resource share. **We recommend that you use AWS RAM to share your private custom domain name.** **API Gateway** With API Gateway, only the AWS CLI is supported. You must update your private custom domain name using a patch operation and provide your own policy document for the `managementPolicy`. 1. Update the `policy` of your private custom domain name and any private APIs mapped to it to grant access to the API consumer's VPC endpoint. For instructions on how to provide your API to another AWS account, see [API provider: Share your private custom domain name using AWS RAM](apigateway-private-custom-domains-provider-share.md). ## Tasks of an API consumer API consumers associate their VPC endpoints with a domain name ARN to invoke a private custom domain name. API consumers don't need to create an API Gateway API. If you are an API consumer, do the following: 1. Create a VPC endpoint with private DNS enabled in Amazon VPC. 1. (Optional - if AWS RAM is used) Accept a private custom domain resource share in AWS RAM within **12 hours** of the resource share. If you and the API provider are in the same organization, the resource share is automatically accepted. 1. Get the private custom domain name ARN. Because the private custom domain name URL is not unique, you use the private custom domain name ARN to form the domain name access association between your VPC endpoint and the private custom domain name. You can use AWS RAM to retrieve the private custom domain name ARN. 1. Associate the private custom domain ARN with your VPC endpoint in API Gateway. This creates a secure connection between your VPC endpoint and the private custom domain name. Traffic doesn't leave the Amazon network. 1. Wait for the API provider to grant your VPC endpoint access to the private custom domain name and any private APIs mapped to the private custom domain name. If you're both the API provider and the API consumer, you grant your own VPC endpoint invoke access. 1. Create a Route 53 Private Hosted Zone and a Route 53 record to resolve the private custom domain name in Route 53. For instructions on how to consume an API in another AWS account, see [API consumer: Associate your VPC endpoint with a private custom domain name shared with you](apigateway-private-custom-domains-consumer-create.md). # Tutorial: Create and invoke a custom domain name for private APIs In this tutorial, you create a private custom domain name that you can invoke in a VPC in your own account. To accomplish this, you are the API provider and the API consumer. You need an existing private API and VPC endpoint to complete this tutorial. If you have a VPC endpoint that you use to access a public custom domain name, don't use it for this tutorial or to create any domain name access associations. ## Step 1: Create a private custom domain name You create your private custom domain name by specifying the domain name, the ACM certificate, and the policy for the `execute-api` service to control which VPC endpoints can invoke it. ------ #### [ AWS Management Console ] **To create a private custom domain name** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Custom domain names**. 1. Choose **Add domain name**. 1. For **Domain name**, enter a domain name. Your ACM certificate must cover this domain name, but the domain name doesn't need to be unique. 1. Select **Private**. 1. For **Routing mode**, choose **API mappings only**. 1. For **ACM certificate**, select a certificate. 1. Choose **Add domain name**. API Gateway provisions a domain name with a `deny` all resource policy. This is the resource policy for the `execute-api` service. You need to update this resource policy to grant access to your VPC endpoints to invoke your private custom domain name. **To update your resource policy** 1. Choose the **Resource policy** tab, and then choose **Edit resource policy**. 1. Enter the following resource policy in the code editor. Replace the VPC endpoint *vpce-abcd1234efg* with your own VPC endpoint ID. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-abcd1234" } } } ] } ``` 1. Choose **Save changes**. ------ #### [ AWS CLI ] When you create a private custom domain name using the AWS CLI, you provide a resource policy for the `execute-api` service to grant access to VPC endpoints to invoke your private custom domain name, using the `--policy file://policy.json` parameter. You can modify this policy later. For this example, you'll attach the following resource policy as the `policy` by loading parameters from a file. Copy and save this file as `policy.json`. This policy only allows incoming traffic to a private custom domain name from the VPC endpoint * `vpce-abcd1234efg`*: **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-abcd1234" } } } ] } ``` The following [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-domain-name.html) command creates a private custom domain name: ``` aws apigateway create-domain-name \ --domain-name 'private.example.com' \ --certificate-arn 'arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef' \ --security-policy 'TLS_1_2' \ --endpoint-configuration '{"types":["PRIVATE"]}' \ --policy file://policy.json ``` The output will like the following. ``` { "domainName": "private.example.com", "domainNameId": "abcd1234", "domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234", "certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef", "certificateUploadDate": "2024-09-10T10:31:20-07:00", "endpointConfiguration": { "types": [ "PRIVATE" ] }, "domainNameStatus": "AVAILABLE", "securityPolicy": "TLS_1_2", "routingMode" : "API_MAPPING_ONLY", "policy": "..." } ``` ------ ## Step 2: Create a base path mapping to map your private API to your private custom domain name After you create your private custom domain name, you map a private API to it. A base path mapping makes an API accessible through the combination of the private custom domain name and an associated base path. We recommend that you use a single private custom domain name as the hostname of multiple private APIs. All API providers need to create a base path mapping, even if you don't plan on invoking your own API. You also need to grant access for VPC endpoints to invoke any private APIs that you map to your private custom domain name. ------ #### [ AWS Management Console ] **To create a base path mapping** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Custom domain names**. 1. Choose a private custom domain name. 1. On the **API mappings** tab, choose **Configure mappings**. 1. Choose **Add new mapping**. 1. Enter an **API**, a **Stage**, and optionally a **Path**. 1. Choose **Save**. ------ #### [ AWS CLI ] The following [create-base-path-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-base-path-mapping.html) command creates a mapping between a private API and a private custom domain name: ``` aws apigateway create-base-path-mapping \ --domain-name-id abcd1234 \ --domain-name 'private.example.com' \ --rest-api-id a1b2c3 \ --stage prod \ --base-path v1 ``` The output will look like the following. ``` { "basePath": "v1", "restApiId": "a1b2c3", "stage": "prod" } ``` ------ For more flexibility on how you route traffic to your APIs, you can change the routing mode to `ROUTING_RULE_ONLY` or `ROUTING_RULE_THEN_API_MAPPING` and create a routing rule. For more information, see [Send traffic to your APIs through your custom domain name in API Gateway](rest-api-routing-mode.md). **Note** If you want other AWS accounts to invoke your private custom domain name, after you complete this tutorial, follow the steps in [API provider: Share your private custom domain name using AWS RAM](apigateway-private-custom-domains-provider-share.md). ## Step 3: Create a domain name access association between your custom domain name and a VPC endpoint Next, you create a domain name access association between your private custom domain name and your VPC endpoint. Your VPC endpoint uses the domain name access association to invoke your private custom domain name while isolated from the public internet. ------ #### [ AWS Management Console ] **To create a domain name access association** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Custom domain names**. 1. Choose a private custom domain name. 1. In the **Resource sharing** tab, for **Domain name access associations**, choose **Create domain name access association**. 1. For **Domain name ARN**, select your domain name. 1. For **VPC endpoint ID**, select the VPC endpoint ID you provided access to in step 1. 1. Choose **Domain name access association**. You can also create your domain name access association using the **Domain name access associations** page of the console. ------ #### [ AWS CLI ] The following `create-domain-name-access-association` command creates a domain name access association between your private custom domain name and your VPC endpoint. ``` aws apigateway create-domain-name-access-association \ --domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 \ --access-association-source vpce-abcd1234efg \ --access-association-source-type VPCE \ --region us-west-2 ``` The output will look like the following. ``` { "domainNameAccessAssociationARN": "arn:aws:apigateway:us-west-2:111122223333:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg", "accessAssociationSource": "vpce-abcd1234efg", "accessAssociationSourceType": "VPCE", "domainNameARN" : "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234" } ``` ------ After you create your domain name access association, it takes about 15 minutes to be ready. While you wait, you can proceed with the following steps. ## Step 4: Create a Route 53 hosted zone After you update your resource policy and associate your private custom domain name with your VPC endpoint, you create a private hosted zone in Route 53 to resolve your custom domain name. A hosted zone is container that holds information about how you want to route traffic for a domain within one or more VPCs without exposing your resources to the internet. For more information, see [Working with private hosted zones](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html). ------ #### [ AWS Management Console ] To use the AWS Management Console, see [Creating a private hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html) in the *Amazon Route 53 Developer Guide*. For **Name**, use the name of your private custom domain name. For **VPC ID**, use the VPC containing the VPC endpoint that you used in the previous steps. ------ #### [ AWS CLI ] The following [create-hosted-zone](https://docs.aws.amazon.com/cli/latest/reference/route53/create-hosted-zone.html) command creates a private hosted zone: ``` aws route53 create-hosted-zone --name private.example.com \ --caller-reference 2014-04-01-18:47 \ --hosted-zone-config Comment="command-line version",PrivateZone=true \ --vpc VPCRegion=us-west-2,VPCId=vpc-abcd1234 ``` The output contains the hosted zone ID. You use the hosted zone ID in the following steps. ------ ## Step 5: Create a Route 53 DNS record After you create the hosted zone, you create an record to resolve your private custom domain name. You use the hosted zone ID you created in the previous step. In this example, you create an A record type. If you are using IPv6 for your VPC endpoint, create an AAAA record type. If you are using dualstack for your VPC endpoint, create both an AAAA and an A record type. ------ #### [ AWS Management Console ] To use the AWS Management Console, see [Routing traffic to an Amazon API Gateway API by using your domain name](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html). Use **Quick create** and turn on **Alias**. For endpoint, use the VPC endpoint DNS name. ------ #### [ AWS CLI ] To configure your DNS records to map the private custom domain name to its hostname of the given hosted zone ID, you create a JSON file that contains the configuration for setting up a DNS record for the private domain name. The following `setup-dns-record.json` shows how to create a DNS `A` record to map a private custom domain name to its private hostname. You provide the `DNSName` of your VPC DNS ID, and the hosted zone ID you created in the previous step. ``` { "Changes": [ { "Action": "UPSERT", "ResourceRecordSet": { "Name": "private.example.com", "Type": "A", "AliasTarget": { "DNSName": "vpce-abcd1234.execute-api.us-west-2.vpce.amazonaws.com", "HostedZoneId": "Z2OJLYMUO9EFXC", "EvaluateTargetHealth": false } } } ] } ``` The following [change-resource-record-sets](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html) command creates a DNS record for your private custom domain name: ``` aws route53 change-resource-record-sets \ --hosted-zone-id ZABCDEFG1234 \ --change-batch file://path/to/your/setup-dns-record.json ``` Replace the`hosted-zone-id` with the Route 53 Hosted Zone ID of the DNS record set in your account. The `change-batch` parameter value points to a JSON file. ------ If you don't plan on invoking your own private custom domain name, after you confirm your private custom domain name is working, you can delete these resources. ## Step 6: Invoke your private custom domain name You can now invoke your private custom domain name in your own AWS account. In your VPC, use the following curl command to access your private custom domain name. ``` curl https://private.example.com/v1 ``` For more information about other ways to invoke your private API, see [Invoke a private API using a custom domain name](apigateway-private-api-test-invoke-url.md#apigateway-private-custom-domains-provider-invoke). ## Step 7: Clean up To prevent unnecessary costs, delete the association between your VPC endpoint and your private custom domain name, and then delete your private custom domain name. ------ #### [ AWS Management Console ] **To delete the domain name access association** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Domain name access associations**. 1. Select your domain name access association, and then choose **Delete**. 1. Confirm your choice, and then choose **Delete**. After you delete your domain name access association, you can delete your private custom domain name. **To delete your private custom domain name** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Custom domain names**. 1. Choose your private custom domain name. 1. Choose **Delete**. 1. Confirm your choice, and then choose **Delete**. If necessary, you can also delete your VPC endpoint. For more information, see [Delete an interface endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html). ------ #### [ AWS CLI ] **To clean up** 1. The following `delete-access-association` command deletes the domain name access association: ``` aws apigateway delete-domain-name-access-association \ --domain-name-access-association-arn 'arn:aws:apigateway:us-west-2:111122223333:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg' \ --region us-west-2 ``` 1. The following `delete-domain-name` command deletes your private custom domain name. This command also removes all base path mappings. ``` aws apigateway delete-domain-name \ --domain-name test.private.com \ --domain-name-id abcd1234 ``` If necessary, you can also delete your VPC endpoint. For more information, see [Delete an interface endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html). ------ ## Best practices We recommend that you use the following best practices when you create your private custom domain name: + Use base path mapping or routing rules to send traffic from one private custom domain name to multiple private APIs. + When a VPC endpoint no longer needs access to a private custom domain name, delete the association. In addition, remove the VPC endpoint from the `policy` for the `execute-api` service for the private custom domain. + Configure at least two Availability Zones per VPC endpoint. + Disable the default endpoint. We recommend that you disable the default endpoint to allow your API consumers to only call your API from the custom domain name. For more information, see [Disable the default endpoint for REST APIs](rest-api-disable-default-endpoint.md). + We recommend that you provision a Route 53 private hosted zone and an A-type record when you set up your private custom domain name. If you don't plan on invoking your own private custom domain name, you can delete these resources later. # Working with cross-account private custom domain names This section explains how to work with cross-account private custom domain names. You can provide a private custom domain name to another AWS account and use another AWS account to invoke a private custom domain name. You can share your private custom domain name to another AWS account using AWS Resource Access Manager or API Gateway. AWS Resource Access Manager (AWS RAM) helps you securely share your resources across AWS accounts and within your organization or organizational units (OUs). For more information, see [What is AWS Resource Access Manager](https://docs.aws.amazon.com/ram/latest/userguide/what-is.html). For instructions on how to share a private custom domain name with another AWS account using AWS RAM, see [API provider: Share your private custom domain name using AWS RAM](apigateway-private-custom-domains-provider-share.md). For instructions on how to share a private custom domain name with another AWS account using API Gateway, see [API provider: Share your private custom domain name using the API Gateway AWS CLI](apigateway-private-custom-domains-provider-share-cli.md). For instructions on how to consume a private custom domain name in another AWS account, see [API consumer: Associate your VPC endpoint with a private custom domain name shared with you](apigateway-private-custom-domains-consumer-create.md). ## Best practices for working with cross-account private custom domain names We recommend the following best practices for working with cross-account private custom domain names: + Use AWS RAM to share your private custom domain names. When you use AWS RAM, you can reduce operational overhead and you don't have to create a `managementPolicy` for the Amazon API Gateway Management service. + Use the `resource-owner` parameter when you list your private custom domain names or domain name access associations. Use the `resource-owner` parameter to only list the resources owned by you or by other AWS accounts. The following example shows how to get all domain name access associations that you own: ``` aws apigateway get-domain-name-access-associations --resource-owner SELF ``` Use `--resource-owner OTHER_ACCOUNTS` to list all the domain name access associations that other accounts have formed with your private custom domain name. # API provider: Share your private custom domain name using AWS RAM You can provide API consumers in other AWS accounts access to your private custom domain name. In this section, you learn how to share your private custom domain name using AWS RAM and how to control access to your private custom domain name. ## Considerations for sharing your private custom domain name The following considerations might impact how you provide access to your private custom domain name using AWS RAM. To learn how to share your private custom domain name without using AWS RAM, see [API provider: Share your private custom domain name using the API Gateway AWS CLI](apigateway-private-custom-domains-provider-share-cli.md). + Private custom domain names are shared at the AWS Region level. Both the private custom domain name and the VPC endpoint need to be in the same AWS Region. + You can use one resource share with multiple principals, and after you create the resource share, you can add more principals to it. We recommend that when possible, you reuse your resource share. + You always need to grant the API consumer's VPC endpoint access to invoke your private custom domain name and any private APIs mapped to it. + If the API consumer and API provider are in the same organization using AWS Organizations, the resource share is automatically accepted. You still need to create the resource share using AWS RAM. + If the API consumer and API provider are in the same organization using AWS Organizations and resource sharing within your organization is enabled, any principals in the organization that you share with are automatically granted access to the resource shares. There is no need for an invitation and you can skip the resource share. + If the API consumer doesn't accept the resource share within **12 hours**, the API provider must share the resource again. + After you create the resource share, AWS RAM updates the `managementPolicy` for the Amazon API Gateway Management service for your private custom domain name to prevent access to principals without explicit `allow` access. For more information, see [Determining whether a request is allowed or denied within an account](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow) in the IAM User Guide. The updated `managementPolicy` will look like the following: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "abcd1234-1234-abcd-abcd-1234abcdefg", "Statement": [ { "Sid": "APIGatewayPrivateDomainNameManagementPolicyDefaultPermission-org", "Effect": "Allow", "Principal": "*", "Action": "apigateway:CreateAccessAssociation", "Resource": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234", "Condition": { "StringEquals": { "aws:PrincipalOrgID": "o-1234abcd" }, "StringNotEquals": { "aws:PrincipalAccount": "111122223333" } } } ] } ``` ------ AWS RAM has prevented principals without explicit `allow` access to create access associations with your private custom domain name, by adding the following: ``` "StringNotEquals": { "aws:PrincipalAccount": "111122223333" } ``` You can still use the principal in the AWS account who created the private custom domain name to create domain name access associations. ## Allow other accounts to create domain name access associations with your private custom domain name First, you grant access to another AWS account to create domain name access associations with your private custom domain name. ------ #### [ AWS Management Console ] To use the AWS Management Console, see [Creating a resource share in AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing-create.html) in the *AWS RAM User Guide*. For **Select resource type**, choose **API Gateway Private Custom Domains**. ------ #### [ AWS CLI ] The following [create-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) creates a resource share for your private custom domain name. It can take a few minutes for the resource and principal associations to complete. For principals, provide an account ID or an Organizations ID, such as `arn:aws:organizations::123456789012:organization/o-1234abcd`. You can provide multiple principals for your resource share. ``` aws ram create-resource-share \ --region us-west-2 \ --name privateCustomDomain-resource-share \ --permission-arns arn:aws:ram::aws:permission/APIGatewayPrivateDomainNameManagementPolicyDefaultPermission \ --resource-arns arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 \ --principals 222222222222 ``` ------ After you have provided access to another AWS account, API consumers in that account must create a domain name access association between their VPC endpoint with your private custom domain name. You can't create the domain name access association for them. For more information, see [Associate your VPC endpoint with a shared private custom domain name](apigateway-private-custom-domains-consumer-create.md#apigateway-private-custom-domains-consumer-associate). ## Allow other accounts to invoke your private custom domain name Next, you grant access for the API consumer's VPC endpoint to invoke your private custom domain name and any private APIs mapped to it. ------ #### [ AWS Management Console ] **To allow VPC endpoints in other accounts to invoke your private custom domain name** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Custom domain names**. 1. Choose the private custom domain name that you shared with other AWS accounts. 1. On the **Resource policy** tab, choose **Edit resource policy**. 1. Add the VPC endpoint ID of the API consumer to your resource policy. You can find the VPC endpoint ID of the API consumer on the **Domain name access associations** section of the **Resource sharing** tab on the **Domain details** page of your private custom domain name. 1. Choose **Save changes**. ------ #### [ AWS CLI ] The following `policy` for the `execute-api` service allows incoming traffic to a private custom domain name from both VPC endpoint `vpce-abcd1234efg` and `vpce-xyz000abc`. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": [ "vpce-abcd1234", "vpce-xyzz0000" ] } } } ] } ``` The following [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) command uses a patch operation to update the `policy` for a private custom domain name: ``` aws apigateway update-domain-name --domain-name private.example.com \ --domain-name-id abcd1234 \ --patch-operations op=replace,path=/policy,value='"{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\",\"Principal\": \"*\",\"Action\": \"execute-api:Invoke\",\"Resource\":[\"execute-api:/*\"]},{\"Effect\": \"Deny\",\"Principal\": \"*\",\"Action\": \"execute-api:Invoke\",\"Resource\":[\"execute-api:/*\"],\"Condition\":{\"StringNotEquals\":[\"vpce-abcd1234efg\", \"vpce-xyz000abc\"]}}}]}" ``` ------ # API provider: Stop sharing a private custom domain name using AWS RAM To stop sharing your private custom domain name, first you stop the API consumer from creating more domain name access associations by dissociating the resource share. Then, you reject the domain name access association and remove the API consumer's VPC endpoint from your `policy` for the `execute-api` service. The API consumer can then delete their domain name access association. ## Stop sharing your private custom domain name First, you stop the resource share using AWS RAM. ------ #### [ AWS Management Console ] To use the AWS Management Console, see [Update a resource share in AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing-update.html). ------ #### [ AWS CLI ] The following [disassociate-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) disassociates a resource share for your private custom domain name. ``` aws ram disassociate-resource-share \ --region us-west-2 \ --resource-arns arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 \ --principals 222222222222 ``` ------ ## Reject the domain name access association After you stop sharing your resource using AWS RAM, you reject the domain name access association between a VPC endpoint in another account and your private custom domain name. **Note** You can't reject a domain name access association in your own account. To stop resource sharing, delete the domain name access association. For more information, see [Delete a domain name access association](apigateway-private-custom-domains-tutorial.md#apigateway-private-custom-domains-cleanup). When you reject a domain name access association with a VPC endpoint, if an API consumer tries to call your private custom domain name, API Gateway rejects the call and returns a `403` status code. ------ #### [ AWS Management Console ] **To reject a domain name access association** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Custom domain names**. 1. Choose the private custom domain name that you shared with other AWS accounts. 1. On the **Resource sharing**, choose the domain name access association you want to reject. 1. Choose **Reject association**. 1. Confirm your choice, and then choose **Reject**. ------ #### [ AWS CLI ] The following `reject-domain-name-access-association` command rejects the domain name access association between the VPC endpoint and your private custom domain name: ``` aws apigateway reject-domain-name-access-association \ --domain-name-access-association-arn arn:aws:apigateway:us-west-2:444455556666:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg \ --domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 ``` ------ ## Deny the API provider access to invoke your private custom domain name After you reject the domain name access association, you remove the API consumer's VPC endpoint from your `policy` for the `execute-api` service. ------ #### [ AWS Management Console ] **To remove the API consumer's VPC endpoint from your resource policy** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Custom domain names**. 1. Choose the private custom domain name that you shared with other AWS accounts. 1. On the **Resource policy** tab, choose **Edit**. 1. Remove the VPC endpoint from the policy. 1. Choose **Save changes**. ------ #### [ AWS CLI ] The following [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) command uses a patch operation to update the `policy` for the `execute-api` service for a private custom domain name. This new `policy` removes an additional VPC endpoint ID added in [Allow other accounts to invoke your private custom domain name](apigateway-private-custom-domains-provider-share.md#apigateway-private-custom-domains-provider-policy-update): ``` aws apigateway update-domain-name --domain-name private.example.com \ --domain-name-id abcd1234 \ --patch-operations op=replace,path=/policy,value='"{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\",\"Principal\": \"*\",\"Action\": \"execute-api:Invoke\",\"Resource\":[\"execute-api:/*\"]},{\"Effect\": \"Deny\",\"Principal\": \"*\",\"Action\": \"execute-api:Invoke\",\"Resource\":[\"execute-api:/*\"],\"Condition\":{\"StringNotEquals\":{\"aws:SourceVpce\": \"vpce-abcd1234efg\"}}}]}" ``` ------ The API consumer should then delete the domain name access association. You can't delete it for them. For more information, see [API consumer: Delete your domain name access association with a private custom domain name](apigateway-private-custom-domains-consumer-delete-domain-name-access-association.md). # API provider: Share your private custom domain name using the API Gateway AWS CLI You can share a private custom domain name using the API Gateway AWS CLI, but we recommend that you use AWS RAM to reduce your operational overhead. For instructions on how to use AWS RAM to share your private custom domain name, see [API provider: Share your private custom domain name using AWS RAM](apigateway-private-custom-domains-provider-share.md). To share a private custom domain name using the API Gateway AWS CLI, you grant other AWS accounts access to create domain name access associations and invoke your private custom domain name. You do this by updating the `managementPolicy` for the API Gateway Management service and the `policy` for the `execute-api` service for your private custom domain name. You also need to grant access for the API consumer's VPC endpoint in the resource policy for any private APIs mapped to your private custom domain name. The API consumer still needs to create a domain name access association in their own account between their VPC endpoint and your private custom domain name. You can't do this for them. ## Grant access to your private custom domain name **To grant access to your private custom domain name** 1. To update the `managementPolicy` for the API Gateway Management service, you create a JSON file that contains the patch operation to update the policy. The following `patch-managementPolicy.json` replaces the current `managementPolicy` with an example policy that grants AWS accounts 111122223333 and 444455556666 access to create domain name access associations with the private custom domain name `private.example.com`. ``` [{ "op": "replace", "path": "/managementPolicy", "value": "{\"Version\":\"2012-10-17\", \"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":[\"arn:aws:iam::111122223333:root\", \"arn:aws:iam::444455556666:root\"]},\"Action\":\"apigateway:CreateAccessAssociation\",\"Resource\":\"arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\"}]}" }] ``` The following [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) command updates the `managementPolicy` using `patch-managementPolicy.json`. ``` aws apigateway update-domain-name \ --domain-name private.example.com \ --domain-name-id abcd1234 \ --patch-operations file://patch-managementPolicy.json ``` Once you grant access, you need to notify the API consumer that they can form the domain name access association. If you use AWS RAM, AWS RAM will do this step for you. 1. To update the `policy` for the `execute-api` service, you create a JSON file that contains the patch operation to update the policy. The following `patch-policy.json` replaces the current `policy` with an example policy that grants two VPC endpoints to invoke the private custom domain name `private.example.com`. ``` [{ "op": "replace", "path": "/policy", "value": "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\",\"Principal\": \"*\",\"Action\": \"execute-api:Invoke\",\"Resource\": \"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\"},{\"Effect\": \"Deny\",\"Principal\": \"*\",\"Action\": \"execute-api:Invoke\",\"Resource\": \"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\",\"Condition\": {\"StringNotEquals\": {\"aws:SourceVpce\": [\"vpce-abcd1234\",\"vpce-xyzz0000\"]}}}]}" }] ``` Use the following [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) command to update the `policy` using `patch-policy.json`. ``` aws apigateway update-domain-name \ --domain-name private.example.com \ --domain-name-id abcd1234 \ --patch-operations file://patch-policy.json ``` ## Deny access to your private custom domain name To stop sharing your private custom domain name, you need to reject the domain name access association between your private custom domain name and the API consumer's VPC endpoint. **To deny access to your private custom domain name** 1. The following `reject-domain-name-access-association` command rejects the domain name access association. ``` aws apigateway reject-domain-name-access-association \ --domain-name-access-association-arn arn:aws:apigateway:us-west-2:444455556666:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234 \ --domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 ``` 1. Modify the `patch-managementPolicy.json` to remove access for the API provider's account to create a domain name access association with your private custom domain name. The following `patch-managementPolicy.json` removes one account from the `managementPolicy`: ``` [{ "op": "replace", "path": "/managementPolicy", "value": "{\"Version\":\"2012-10-17\", \"Statement\":[{\"Effect\":\"Allow\",\"Principal\":\"*\",\"Action\":\"apigateway:CreateAccessAssociation\",\"Resource\":\"arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\"}]}" }] ``` The following [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) command to updates the `managementPolicy` using `patch-managementPolicy.json`. ``` aws apigateway update-domain-name \ --domain-name private.example.com \ --domain-name-id abcd1234 \ --patch-operations file://patch-managementPolicy.json ``` 1. Modify the `patch-policy.json` to remove access for the API provider's VPC endpoint to invoke your private custom domain name. The following `patch-policy.json` removes the VPC endpoint ID from the `policy`: ``` [{ "op": "replace", "path": "/policy", "value": "{\"Version\":\"2012-10-17\", \"Statement\":[{\"Effect\":\"Allow\",\"Principal\":\"*\",\"Action\":\"execute-api:Invoke\",\"Resource\":\"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\"},{\"Effect\":\"Deny\",\"Principal\":\"*\",\"Action\":\"execute-api:Invoke\",\"Resource\":\"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\",\"Condition\":{\"StringNotEquals\":{\"aws:SourceVpce\":\"vpce-abcd1234\"}}}]}" }] ``` The following [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) command updates the `policy` using `patch-policy.json`. ``` aws apigateway update-domain-name \ --domain-name private.example.com \ --domain-name-id abcd1234 \ --patch-operations file://patch-policy.json ``` ## Example policies used in this procedure The following section shows the example policies used in the previous procedure. The following example policy is for the `managementPolicy` for the Amazon API Gateway Management service. This policy grants AWS accounts 111122223333 and 444455556666 access to create domain name access associations with the private custom domain name `private.example.com`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "111122223333", "444455556666" ] }, "Action": "apigateway:CreateAccessAssociation", "Resource": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+a1b2c3" } ] } ``` ------ The following example policy is the policy for the `policy` for the `execute-api` service. This policy grants VPC endpoints `vpce-abcd1234` and `vpce-xyzz0000` access to invoke the private custom domain name. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234" }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234", "Condition": { "StringNotEquals": { "aws:SourceVpce": [ "vpce-abcd1234", "vpce-xyzz0000" ] } } } ] } ``` ------ # API consumer: Associate your VPC endpoint with a private custom domain name shared with you The following procedure shows how to consume a private domain name in another AWS account. Depending on your trust relationship with the API provider, AWS RAM might complete some tasks for you. When you are in a different AWS account from a private custom domain name, you can only associate your VPC endpoint with a private custom domain name and invoke it. You can't view the `policy` or any other parameters of the private custom domain name. ## Prerequisites The following prerequisites are required to consume a private custom domain name in another AWS account: + A VPC and a VPC endpoint for the `execute-api` service. Your VPC must have `enableDnsHostnames` and `enableDnsSupport` set to `true`. + We recommend that you configure at least two Availability Zones per VPC endpoint. ## (Optional) Accept the private custom domain resource share If your API provider used AWS RAM to create a resource share, you have **12 hours** to accept it. If you are in the same organization using AWS Organizations as the API provider, the share is automatically accepted. If you are in an organization that has automatic shared resources enabled, the resource is automatically shared with you. ------ #### [ AWS Management Console ] To use the AWS Management Console, see [Accepting and rejecting resource share invitations](https://docs.aws.amazon.com/ram/latest/userguide/working-with-shared-invitations.html) in the *AWS RAM User Guide*. ------ #### [ AWS CLI ] To find all resources shared with you, use the following [get-resource-share-invitations](https://docs.aws.amazon.com/cli/latest/reference/ram/get-resource-share-invitations.html) command: ``` aws ram get-resource-share-invitations \ --region us-west-2 ``` Use the resulting resource share ARN to accept the resource share invitation. The following [accept-resource-share-invitation](https://docs.aws.amazon.com/cli/latest/reference/ram/accept-resource-share-invitation.html) command accepts the resource share. ``` aws ram accept-resource-share-invitation \ --resource-share-invitation-arn arn:aws:ram:us-west-2:123456789012:resource-share-invitation/1e3477be-4a95-46b4-bbe0-c4001EXAMPLE \ --region us-west-2 ``` ------ ## Associate your VPC endpoint with a shared private custom domain name Because private custom domain names aren't unique, you associate your VPC endpoint with the unique custom domain name ARN. After you create your domain name access association, it can take up to 15 minutes for your VPC endpoint to successfully invoke your private custom domain name. If you have a VPC endpoint that you use to access a public custom domain name, don't use it to create any domain name access associations. ------ #### [ AWS Management Console ] **To associate your VPC endpoint with a shared private custom domain name** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Domain name access associations**. 1. Choose **Create domain name access association**. 1. For **Domain name ARN**, select the domain name ARN that the API provider shared with you. The domain name ARN might not appear in the dropdown list. You can use the AWS RAM console to view domain names shared with you and then copy the domain name ARN and enter it into this field. 1. For **VPC endpoint ID**, select the VPC endpoint ID you want to form the domain name access association with. 1. Choose **Create domain name access association**. ------ #### [ AWS CLI ] Because private custom domain names aren't unique, you associate your VPC endpoint with the unique custom domain name ARN. To find the domain name ARN, use one of the following commands. 1. **AWS RAM** The following [list-resources](https://docs.aws.amazon.com/cli/latest/reference/ram/list-resources.html) command lists resources that are shared with you. The API provider must have used AWS RAM to share their private custom domain with you to use this command. ``` aws ram list-resources \ --resource-owner OTHER-ACCOUNTS \ --region us-west-2 --resource-type apigateway:Domainnames ``` **API Gateway** The following `get-domain-names` command lists all private custom domain names owned by other AWS accounts that you can form domain name access associations with. ``` aws apigateway get-domain-names \ --resource-owner OTHER_ACCOUNTS \ --region us-west-2 ``` 1. After your retrieve the ARN, use API Gateway to create the domain name access association between your VPC endpoint and a shared private custom domain name. Use the following `create-domain-name-access-association` command: ``` aws apigateway create-domain-name-access-association \ --access-association-source-type VPCE \ --access-association-source 'vpce-1a2b3c4d5e6f1a2b3' \ --domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234" ``` The output will look like the following. ``` { "domainNameAccessAssociationARN": "arn:aws:apigateway:us-west-2:444455556666:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg", "accessAssociationSource": "vpce-1a2b3c4d5e6f1a2b3", "accessAssociationSourceType": "VPCE", "domainNameARN" : "arn:aws:apigateway:us-west-1:111122223333:/domainnames/private.example.com+a1b2c3" } ``` ------ After you associate your VPC endpoint with the private custom domain name, confirm that your API provider has updated the policy of their private custom domain name to allow your VPC endpoint to invoke their domain name. For more information, see [Allow other accounts to invoke your private custom domain name](apigateway-private-custom-domains-provider-share.md#apigateway-private-custom-domains-provider-policy-update). ## Create a Route 53 hosted zone To resolve the private custom domain name, you need to create a Route 53 private hosted zone. A hosted zone is container that holds information about how you want to route traffic for a domain within one or more VPCs without exposing your resources to the internet. For more information, see [Working with private hosted zones](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html). ------ #### [ AWS Management Console ] To use the AWS Management Console, see [Creating a private hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html) in the *Amazon Route 53 Developer Guide*. For **Name**, use the name of the private custom domain name. For **VPC ID**, use the VPC containing the VPC endpoint that you used for your domain name access association. ------ #### [ AWS CLI ] The following [create-hosted-zone](https://docs.aws.amazon.com/cli/latest/reference/route53/create-hosted-zone.html) command creates a private hosted zone: ``` aws route53 create-hosted-zone --name private.example.com \ --caller-reference 2014-04-01-18:47 \ --hosted-zone-config Comment="command-line version",PrivateZone=true \ --vpc VPCRegion=us-west-2,VPCId=vpc-abcd1234 ``` The output contains the hosted zone ID. You use the hosted zone ID in the following steps. ------ ## Create a Route 53 DNS record After you create the hosted zone, you create an record to resolve the private custom domain. In this example, you create an A record type. If you are using IPv6 for your VPC endpoint, create an AAAA record type. If you are using dualstack for your VPC endpoint, create both an AAAA and an A record type. ------ #### [ AWS Management Console ] To use the AWS Management Console, see [Routing traffic to an Amazon API Gateway API by using your domain name](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html). Use **Quick create** and turn on **Alias**. For endpoint, use the VPC endpoint DNS name. ------ #### [ AWS CLI ] To configure your DNS records to map the private custom domain name to its hostname of the given hosted zone ID, first create a JSON file that contains the configuration for setting up a DNS record for the private domain name. The following `setup-dns-record.json` shows how to create a DNS `A` record to map a private custom domain name to its private hostname. You provide the `DNSName` of your VPC DNS ID, and the hosted zone ID you created in the previous step. ``` { "Changes": [ { "Action": "UPSERT", "ResourceRecordSet": { "Name": "private.example.com", "Type": "A", "AliasTarget": { "DNSName": "vpce-abcd1234.execute-api.us-west-2.vpce.amazonaws.com", "HostedZoneId": "Z2OJLYMUO9EFXC", "EvaluateTargetHealth": false } } } ] } ``` The following [change-resource-record-sets](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html) command creates a DNS record for the private custom domain name: ``` aws route53 change-resource-record-sets \ --hosted-zone-id ZABCDEFG1234 \ --change-batch file://path/to/your/setup-dns-record.json ``` Replace the`hosted-zone-id` with the Route 53 Hosted Zone ID of the DNS record set in your account. The `change-batch` parameter value points to a JSON file. ------ ## Next steps for an API consumer You can now invoke the private API in your own AWS account. In your VPC, you can use the following curl command to access your private custom domain name. ``` curl https://private.example.com/v1 ``` For more information about other ways to invoke your private API, see [Invoke a private API using a custom domain name](apigateway-private-api-test-invoke-url.md#apigateway-private-custom-domains-provider-invoke). # API consumer: Delete your domain name access association with a private custom domain name If you are an API consumer, at any time, you can delete the access association resource. The API provider can't delete the domain name access association for you. We recommend that you always delete a domain name access association when you're no longer using it. ------ #### [ AWS Management Console ] **To delete the domain name access association** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. In the main navigation pane, choose **Domain name access associations**. 1. Select your domain name access association, and then choose **Delete**. 1. Confirm your choice, and then choose **Delete**. ------ #### [ AWS CLI ] The following `delete-access-association` command deletes the access association: ``` aws apigateway delete-domain-name-access-association \ --domain-name-access-association-arn 'arn:aws:apigateway:us-west-2:444455556666:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg' ``` ------ # Create a custom domain name for private APIs using CloudFormation The following example CloudFormation template creates a private API and a private custom domain name, maps the private API to the custom domain name, and then creates a domain name access association. You need to provide your own VPC endpoint, domain name, and certificate ARN. The following considerations might impact your use of CloudFormation to create a private custom domain name: + You can't reject a domain name access association using CloudFormation. To reject a domain name access association, use the AWS CLI. + Use the `AWS::ApiGateway::DomainNameV2` CloudFormation property to create a private custom domain name. + Use the `AWS::ApiGateway:BasePathMappingV2` CloudFormation property to create a base path mapping. ``` AWSTemplateFormatVersion: 2010-09-09 Parameters: EndpointID: Type: String Default: vpce-abcd1234567efg Description: A VPC endpoint with enableDnsHostnames and enableDnsSupport set to true. DomainName: Type: String Default: private.example.com Description: A domain name that you own. CertificateArn: Type: String Default: arn:aws:acm:us-west-2:123456789:certificate/abcd-000-1234-0000-000000abcd Description: An ACM certificate that covers the domain name. Resources: PrivateApi: Type: 'AWS::ApiGateway::RestApi' Properties: EndpointConfiguration: Types: - PRIVATE VpcEndpointIds: - !Ref EndpointID Name: private-api Policy: Statement: - Action: 'execute-api:Invoke' Effect: Allow Principal: '*' Resource: 'execute-api:/*' - Action: 'execute-api:Invoke' Condition: StringNotEquals: 'aws:SourceVpce': !Ref EndpointID Effect: Deny Principal: '*' Resource: 'execute-api:/*' Version: 2012-10-17 PrivateApiDeployment: Type: 'AWS::ApiGateway::Deployment' Properties: RestApiId: !Ref PrivateApi Description: Private API deployment DependsOn: - PrivateApiMethod PrivateApiStage: Type: 'AWS::ApiGateway::Stage' Properties: RestApiId: !Ref PrivateApi DeploymentId: !Ref PrivateApiDeployment StageName: prod PrivateApiMethod: Type: 'AWS::ApiGateway::Method' Properties: HttpMethod: ANY ResourceId: !GetAtt PrivateApi.RootResourceId RestApiId: !Ref PrivateApi AuthorizationType: NONE Integration: Type: MOCK RequestTemplates: application/json: "{\"statusCode\": 200}" IntegrationResponses: - StatusCode: '200' MethodResponses: - StatusCode: '200' PrivateDomainName: Type: AWS::ApiGateway::DomainNameV2 Properties: DomainName: !Ref DomainName CertificateArn: !Ref CertificateArn EndpointConfiguration: Types: - PRIVATE SecurityPolicy: TLS_1_2 Policy: Statement: - Action: 'execute-api:Invoke' Effect: Allow Principal: '*' Resource: 'execute-api:/*' - Action: 'execute-api:Invoke' Condition: StringNotEquals: 'aws:SourceVpce': !Ref EndpointID Effect: Deny Principal: '*' Resource: 'execute-api:/*' Version: 2012-10-17 PrivateBasePathMapping: Type: AWS::ApiGateway::BasePathMappingV2 DependsOn: - PrivateApiStage Properties: BasePath: prod DomainNameArn: !GetAtt PrivateDomainName.DomainNameArn RestApiId: !Ref PrivateApi Stage: prod DomainNameAccessAssociation: Type: AWS::ApiGateway::DomainNameAccessAssociation Properties: DomainNameArn: !GetAtt PrivateDomainName.DomainNameArn AccessAssociationSource: !Ref EndpointID AccessAssociationSourceType: VPCE ``` # Invoke a private API You can only invoke a private API from within a VPC using a VPC endpoint. Your private API must have a resource policy that allows specific VPCs and VPC endpoints to invoke your API. If you invoke a private API without using a custom domain name or private DNS names and your APIs or domain name uses a security policy that starts with `SecurityPolicy_`, you must set the endpoint access mode to `BASIC`. For more information, see [Endpoint access mode](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode). ## Invoke a private API using a custom domain name To invoke a private API using a custom domain name, your VPC endpoint needs a domain name access association with a custom domain name, and the custom domain name needs to allow access for the VPC endpoint to invoke it. For more information, see [Custom domain names for private APIs in API Gateway](apigateway-private-custom-domains.md). There are no differences between invoking a private custom domain name in a VPC in your own AWS account or in a different AWS account. ### Use your custom domain name Inside your VPC, you can invoke your API using the custom domain name. The following example is a curl command to invoke your private custom domain name: ``` curl https://private.example.com ``` ### Use endpoint-specific private DNS hostnames You can invoke your API using the custom domain name and the endpoint-specific private DNS hostname. ``` curl https://private-dns-hostname.execute-api.region.vpce.amazonaws.com/basepath -H 'Host:custom-domain-name' ``` The following example is a curl command to invoke your custom domain name using an endpoint-specific private DNS hostname: ``` curl https://vpce-123456-abc000.execute-api.us-east-2.vpce.amazonaws.com/test -H 'Host:private.example.com' ``` ## Invoke a private API without using a custom domain name To invoke your private API without using a custom domain name, you need to identify the DNS names for your API. The following procedure shows how to find your DNS names. ------ #### [ AWS Management Console ] **To find the DNS names** 1. Sign in to the AWS Management Console and open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/). 1. In the main navigation pane, choose **Endpoints** and then choose your interface VPC endpoint for API Gateway. 1. In the **Details** pane, you'll see five values in the **DNS names** field. The first three are the public DNS names for your API. The other two are the private DNS names for it. ------ #### [ AWS CLI ] Use the following [describe-vpc-endpoints](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-vpc-endpoints.html) command to list your DNS values. ``` aws ec2 describe-vpc-endpoints --vpc-endpoint-ids vpce-01234567abcdef012 ``` The first three are the public DNS names for your API. The other two are the private DNS names for it. ------ ### Invoke a private API using a Route53 alias You can associate or disassociate a VPC endpoint with your private API. For more information, see [(Optional) Associate or disassociate a VPC endpoint with a private API](apigateway-private-api-create.md#associate-private-api-with-vpc-endpoint). After you associate your VPC endpoints with your private API, you can use the following base URL to invoke the API: ``` https://{rest-api-id}-{vpce-id}.execute-api.{region}.amazonaws.com/{stage} ``` For example, if you set up the `GET /pets` method for the `test` stage, and your REST API ID was `01234567ab`, and your VPC endpoint ID was `vpce-01234567abcdef012`, and your Region was `us-west-2`, you can invoke your API as: ``` curl -v https://01234567ab-vpce-01234567abcdef012.execute-api.us-west-2.amazonaws.com/test/pets ``` ### Invoke a private API using private DNS names If you've enabled private DNS, you can access your private API using the following private DNS name: ``` {restapi-id}.execute-api.{region}.amazonaws.com ``` The base URL to invoke the API is in the following format: ``` https://{restapi-id}.execute-api.{region}.amazonaws.com/{stage} ``` For example, if you set up the `GET /pets` method for the `test` stage, and your REST API ID was `01234567ab` and your Region was `us-west-2`, you could invoke your private API by entering the following URL in a browser: ``` https://01234567ab.execute-api.us-west-2.amazonaws.com/test/pets ``` Alternatively, you could use the following cURL command to invoke your private API: ``` curl -X GET https://01234567ab.execute-api.us-west-2.amazonaws.com/test/pets ``` **Warning** If you enable private DNS for your VPC endpoint, you won't be able to access the default endpoint for public APIs. For more information, see [Why can't I connect to my public API from an API Gateway VPC endpoint?](https://repost.aws/knowledge-center/api-gateway-vpc-connections). ### Invoke a private API using Direct Connect You can use Direct Connect to establish a dedicated private connection from an on-premises network to Amazon VPC and access your private API endpoint over that connection by using public DNS names. You can also use private DNS names to access your private API from an on-premises network by setting up an Amazon Route 53 Resolver inbound endpoint and forwarding it all DNS queries of the private DNS from your remote network. For more information, see [Forwarding inbound DNS queries to your VPCs](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver-forwarding-inbound-queries.html) in the *Amazon Route 53 Developer Guide*. ### Invoke a private API using endpoint-specific public DNS hostnames You can access your private API using endpoint-specific DNS hostnames. These are public DNS hostnames containing the VPC endpoint ID or API ID for your private API. The generated base URL is in the following format: ``` https://{public-dns-hostname}.execute-api.{region}.vpce.amazonaws.com/{stage} ``` For example, if you set up the `GET /pets` method for the `test` stage, and your REST API ID was `abc1234`, its public DNS hostname was `vpce-def-01234567`, and your Region was `us-west-2`, you could invoke your private API using its VPCe ID by using the `Host` header in a cURL command: ``` curl -v https://vpce-def-01234567.execute-api.us-west-2.vpce.amazonaws.com/test/pets -H 'Host: abc1234.execute-api.us-west-2.amazonaws.com' ``` Alternatively, you can invoke your private API via its API ID by using the `x-apigw-api-id` header in a cURL command in the following format: ``` curl -v https://{public-dns-hostname}.execute-api.{region}.vpce.amazonaws.com/{stage} -H 'x-apigw-api-id:{api-id}' ```