How do I use an interface VPC endpoint to access an API Gateway private REST API in another account?

Short description

To use an interface VPC endpoint to access an API Gateway private REST API that's in another AWS account, complete the following steps:

1. Create an interface endpoint in an Amazon Virtual Private Cloud (Amazon VPC) in one account (account A).
2. Create an API Gateway private REST API in a second account (account B).
3. Configure a resource policy for the private REST API that allows the interface endpoint to invoke the API.
4. Set up a method for the private REST API.
5. Deploy the private REST API.
6. Call the private REST API from account A to test the setup.

Note: The Amazon API Gateway private REST API and the VPC endpoint must be in the same AWS Region.

Resolution

Create an interface endpoint in an Amazon VPC in one account (account A)

Create a new interface VPC endpoint

From account A, follow the instructions in Create an interface VPC endpoint for API Gateway execute-api.

Important: For Policy, choose Full access. It's a best practice to use a VPC endpoint policy to restrict endpoint access by API ID. It's also a best practice to use the API Gateway resource policy to restrict endpoint access by principal. For more information, see Apply least-privilege permissions.

When you create the interface endpoint, take the following actions:

• It's a best practice to select multiple subnets in different Availability Zones. When you configure subnets across multiple Availability Zones, your interface endpoint is more resilient to potential AZ failures.
• Activate private DNS to use public or private DNS to connect to your private REST API.
  Note: When you activate private DNS for an interface VPC endpoint, you can't access API Gateway public APIs from your Amazon VPC. For more information, see Why do I get an HTTP 403 Forbidden error when connecting to my API Gateway APIs from a VPC?
• Your security groups must have a rule that allows TCP Port 443 inbound HTTPS traffic from one an IP address range in your Amazon VPC. The rule can also be from another security group in your Amazon VPC.
  Note: If you don't have a security group that meets either of these requirements, then create a new security group. If you don't specify a security group, then a default security group is associated with the endpoint network interfaces.

Get the interface endpoint's VPC Endpoint ID

After you create the interface endpoint, the VPC Endpoint ID is displayed. Copy the VPC Endpoint ID of your new interface endpoint, for example: vpce-1a2b3c456d7e89012. Then, choose Close.

Note: Use this ID when you create and configure your private REST API.

Get the interface endpoint's public DNS name

After you choose Close, the Endpoints page is displayed in the Amazon VPC console. On the Details tab of the Endpoints page, in the DNS names column, copy the public DNS name for your interface endpoint, for example: vpce-1a2b3c456d7e89012-f3ghijkl.execute-api.region.vpce.amazonaws.com.

Create an API Gateway private REST API in a second account (account B)

1. In account B, open the API Gateway console.
2. Choose Create API.
3. For Choose an API type, Under REST API Private, choose Build.
4. On the Create page, keep Choose the protocol set to REST.
5. For Create new API, choose New API.
6. Under Settings, enter the following information:
   For API name, enter a name.
   (Optional) For Description, enter a description.
   Set Endpoint Type set to Private.
   For VPC Endpoint IDs, enter your interface endpoint ID. Then, choose Add.
   Note: When you associate your interface endpoint with your private REST API, API Gateway generates a new Amazon Route 53 alias record. You can use the Route53 alias to access your private API.
7.  Choose Create API.

For more information, see Creating a private API in Amazon API Gateway.

Configure a resource policy for the private REST API that allows the interface endpoint to invoke the API

1.    In the navigation pane of the API Gateway console, under your API, choose Resource Policy.

2.    On the Resource Policy page, enter the following example resource policy into the text box:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Deny",
      "Principal": "*",
      "Action": "execute-api:Invoke",
      "Resource": "execute-api:/*/*/*",
      "Condition": {
        "StringNotEquals": {
          "aws:sourceVpce": "vpce-1a2b3c456d7e89012"
        }
      }
    },
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "execute-api:Invoke",
      "Resource": "execute-api:/*/*/*"
    }
  ]
}

Note: Replace vpce-1a2b3c456d7e89012 with the interface endpoint ID.

For more information, see Set up a resource policy for a private API.

Set up a method for the private REST API

1. In the navigation pane of the API Gateway console, under your API, choose Resources.
2. On the Resources pane, choose Actions, and then choose Create Method.
3. In the dropdown list under the / resource node, choose ANY, and then choose the check mark icon.
4.  On the / - ANY - Setup pane, for Integration type, choose Mock.
   Note: A mock integration responds to any request that reaches it.
5. Choose Save.

For more information, see Set up REST API methods in API Gateway.

Deploy the private REST API

1. On the Resources pane of the API Gateway console, choose Actions, and then choose Deploy API.
2. In the Deploy API dialog box, enter the following information:
   For Deployment stage, choose [New Stage].
   For Stage name, enter a name, for example dev or test.
3. Choose Deploy.
4.  On the Stage Editor pane, find the message: If Private DNS is enabled, use this URL:. Copy your private REST API's invoke URL.
   Note: Use the private REST API's invoke URL to test the setup.

For more information, see Deploy a private API using the API Gateway console.

Call the private REST API from account A to test the setup

1. In account A, launch an Amazon Elastic Compute Cloud (Amazon EC2) instance in the same Amazon VPC as your interface endpoint.
   Important: Choose the security group that you associated with your interface endpoint.
2. Connect to the Amazon EC2 instance.
   Note: An EC2 instance can incur charges on your AWS account. If you create an instance to test, then terminate the instance when you're done to prevent recurring charges.
3. From the command line of your Amazon EC2 instance, run any of the following curl commands to call the private REST API in account B.
   Note: For more information, see Invoking your private API using endpoint-specific public DNS hostnames. For more information about curl, see the curl project website.

For a private DNS name

Run the following command:

curl -i https://a1bc234d5e.execute-api.region.amazonaws.com/stage-name

Note: Replace https://a1bc234d5e.execute-api.region.amazonaws.com/stage-name with your private API's invoke URL. This command works only if you turned on private DNS for your interface endpoint. For more information, see Invoking your private API using private DNS names.

For a Route 53 alias 

Run the following command:

curl -i https://a1bc234d5e-vpce-1a2b3c456d7e89012.execute-api.region.amazonaws.com/stage-name

Note: Replace a1bc234d5e with your API's ID, vpce-1a2b3c456d7e89012 with the interface endpoint ID, and region with your API's Region. Replace stage-name with the name of the stage where you deployed your private API. For more information, see Accessing your private API using a Route53 alias.

For a public DNS name with a host header

Run the following command:

curl -i https://vpce-1a2b3c456d7e89012-f3ghijkl.execute-api.region.vpce.amazonaws.com/stage-name -H "Host: a1bc234d5e.execute-api.region.amazonaws.com"

Note: Replace vpce-1a2b3c456d7e89012-f3ghijkl.execute-api.region.vpce.amazonaws.com with your interface endpoint's public DNS name and stage-name with the name of the stage where you deployed your private API. Replace a1bc234d5e.execute-api.region.amazonaws.com with your private API's invoke URL.

For a public DNS name with the x-apigw-api-id header

Run the following command:

curl -i https://vpce-1a2b3c456d7e89012-f3ghijkl.execute-api.region.vpce.amazonaws.com/stage-name -H "x-apigw-api-id:a1bc234d5e"

Note: Replace vpce-1a2b3c456d7e89012-f3ghijkl.execute-api.region.vpce.amazonaws.com with your interface endpoint's public DNS name and stage-name with the name of the stage where you deployed your private API. Replace a1bc234d5e with your API's ID.

4.    Review the command output. API Gateway returns a 200 OK response when the connection is successful.

Related information

How do I troubleshoot issues when connecting to an API Gateway private API endpoint?

Access an AWS service using an interface VPC endpoint

Multi-Region private API gateway