How do I connect to a private API Gateway over a Direct Connect connection?

5 minute read

I want to connect to a private Amazon API Gateway over an AWS Direct Connect connection.


Create an Amazon Virtual Private Cloud (Amazon VPC) endpoint for the Amazon API Gateway service

An Amazon VPC endpoint allows private resources in a VPC to securely communicate with the API Gateway service. To create an Amazon VPC endpoint for API Gateway, follow these steps:

  1. Open the Amazon VPC console.
  2. In the navigation pane, under Virtual Private Cloud, choose Endpoints.
  3. For Service Category, choose AWS Services.
  4. For Service Name, search by keyword for "execute-api". This search returns a single result: "com.amazonaws.REGION.execute-api".
  5. Select "com.amazonaws.REGION.execute-api".
  6. For VPC, select the Amazon VPC where your Direct Connect connection is configured.
  7. For Subnets, select the subnets where you want the API to be accessible.
  8. For Enable DNS name, clear the Enable for this endpoint box. Turning off this setting requires that the Amazon VPC has "DNS hostnames" is turned on, which is an optional feature. Leaving this setting turned on breaks all access to public API Gateway APIs in the deployed Amazon VPC if the VPC uses the Amazon provided DNS.
  9. For Security group, choose the security group for the Amazon VPC endpoint. The security group must allow access on TCP/443 inbound from your Amazon VPC.
  10. For Policy, choose Full Access. This option allows all connections from your Amazon VPC to the VPC endpoint using AWS IAM permissions.
  11. Choose Create Endpoint.
  12. Note the Amazon VPC Endpoint ID (for example, "vpce-01234567890abcdef"). You need this ID later to edit the API's resource policy.

Create your private REST API, if you don't already have one

  1. Open the API Gateway console.
  2. Select the Region of your Direct Connect connection.
  3. Choose Create API.
  4. For API type, choose REST API Private.
  5. For API protocol, choose REST.
  6. Under Create a New API, choose Example API.
  7. Under Settings, confirm that Endpoint Type is set to Private.
  8. Choose Import.

Grant the Amazon VPC endpoint permission to access the private REST API

  1. On the API Management page, choose Resource Policy.
  2. Copy the policy below into your Resource Policy.
      "Version": "2012-10-17",
      "Statement": [
          "Effect": "Deny",
          "Principal": "*",
          "Action": "execute-api:Invoke",
          "Resource": "execute-api:/*/*/*",
          "Condition": {
            "StringNotEquals": {
              "aws:sourceVpce": "{{vpceID}}"
          "Effect": "Allow",
          "Principal": "*",
          "Action": "execute-api:Invoke",
          "Resource": "execute-api:/*/*/*"
    Replace the {{vpceID}} string with the Amazon VPC Endpoint ID that you noted after creating the VPC endpoint. Or, find the ID in the Amazon VPC console under Endpoints.
    Note: This example policy allows access to all resources on the API from your Amazon VPC. To further restrict access, modify the Resource key.
  3. Choose Save.

Deploy your API to commit the changes

Now that you've created the API and added a resource policy, deploy the API to a stage to implement your changes:

  1. On the API Gateway console, choose Resources from the navigation pane.
  2. Choose Actions.
  3. Under API Actions, choose Deploy API.
  4. For Deployment stage, choose [New Stage].
  5. Enter a name for the stage.
  6. Choose Deploy. The changes are deployed to the API. This process can take a few minutes to propagate.

Test access to the API from the Direct Connect connection

Follow these steps to test access:

  1. On the Amazon VPC console, choose Endpoints, and then select the VPC endpoint that you created.

  2. Under Details, copy the DNS name for the VPC endpoint. For example,

  3. From a computer with a connection to your Amazon VPC using Direct Connect, run one of the following commands to test the DNS hostname resolution of the VPC endpoint.

    Windows PowerShell:

    nslookup <YOUR_VPCE_HOSTNAME>



    nslookup <YOUR_VPCE_HOSTNAME>

    Note: Replace YOUR_VPCE_HOSTNAME with the hostname of the VPC endpoint you created earlier.

    The response returns a private IP address that corresponds to your Amazon VPC endpoint. If you don't receive a private IP address in the response, then check the Amazon VPC endpoint hostname on the Amazon VPC console under Endpoints.

  4. If DNS is working, then make a test HTTP request. To do this, you need the API ID from the API Gateway console. Copy the API ID from the list. The API ID is a string of characters, such as "chw1a2q2xk."

  5. From an on-premises computer connected to the Direct Connect connection, run the following command:

    Windows PowerShell:

    curl -H @{'x-apigw-api-id' = '<YOUR_API_ID>'} https://<YOUR_VPCE_HOSTNAME>/<STAGE>



    curl -IX GET -H 'x-apigw-api-id:<YOUR_API_ID>' https://<YOUR_VPCE_HOSTNAME>/<STAGE>

    Note: Replace YOUR_API_ID with the ID of your private REST API or the API that you created earlier. Replace YOUR_VPCE_HOSTNAME with hostname of VPC endpoint and STAGE with the deployment stage that you created earlier.

Make sure of the following:

  • The first line of the response includes "HTTP/1.1 200 OK."
  • If you don't receive a response, then check that the security group associated with the Amazon VPC endpoint allows inbound connections on TCP/443 from your source IP address. Also check that your connection is correctly using your Direct Connect connection.
  • If you receive a "403 Forbidden" response, then check that you have set the <YOUR_API_ID> header. Confirm that you're sending a GET request. Also, check that the <STAGE> was correctly added.

Note: Client web applications served from a domain different from this API might interact with this API. In such cases, the browser generates a preflight request of CORS that makes it difficult to set the x-apigw-api-id header. To resolve this issue, access the private API using a Route53 alias, instead.

Related information

What is CORS?

How can I troubleshoot Direct Connect gateway routing issues?

How can I set up a Direct Connect gateway?

AWS OFFICIALUpdated 5 months ago