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

Last updated: 2019-08-30

I'm getting a "Forbidden" error or having other issues connecting to an Amazon API Gateway private API endpoint in an Amazon Virtual Private Cloud (Amazon VPC). How do I fix these issues?

Short Description

In your Amazon VPC, there might be AWS resources such as Amazon Elastic Compute Cloud (Amazon EC2) instances or AWS Lambda functions. If those resources can't connect to a private API endpoint, it could be because:

If you can't connect to a private API endpoint from an external client (such as an Amazon VPC in another AWS account, or an on-premises network), there could be an issue with the resource policy or the DNS name used.

Resolution

If you haven't already, set up API execution logging. When configuring the logging settings, for Log level, choose INFO. Select Log full requests/responses data, too. The logs generated using these settings can help you further troubleshoot the cause of the issue.

Note: If the logs don't populate after an attempt to access the private API endpoint, that can indicate that the request didn't reach the endpoint. Make sure that the private API's invoke URL is correctly formatted.

Resource policy

The error message "Forbidden" can occur if the attached API Gateway resource policy is incorrectly configured and you try to access the private API endpoint.

The error message "User: anonymous is not authorized to perform: execute-api:Invoke on resource:..." occurs if the resource policy isn't correctly configured to allow traffic from the interface VPC endpoint to the private API endpoint.

To resolve these errors, make sure to create and attach a resource policy that's correctly configured for access. Use these example resource policies as a guideline.

After changing the resource policy, redeploy your API for the changes to take effect.

VPC endpoint policy

The error message "User: anonymous is not authorized to perform: execute-api:Invoke on resource:..." can also occur if you use a VPC endpoint policy with your interface VPC endpoint and the policy restricts access.

Make sure that your VPC endpoint policy allows the client that's making requests to access the private API. For more information, see VPC Endpoint Policy Examples.

VPC security groups

The error "Connection timed out" can indicate that the rules for your Amazon VPC's security groups aren't correctly configured.

As a test, run this command from the client that's making requests to access the private API:

Note: Replace vpce-id with your VPC endpoint ID. Replace region with the AWS Region of your interface VPC endpoint.

$ telnet vpce-id.execute-api.region.vpce.amazonaws.com 443

If the connection times out, check your VPC configuration to make sure that:

  • The security group for the AWS resource that's making requests is correctly configured. It must have a security group rule that allows TCP Port 443 outbound traffic to the interface VPC endpoint's IP address range or security group.
  • The interface VPC endpoint's security group is correctly configured. It must have a rule that allows TCP Port 443 inbound traffic from the IP address range or security group of the AWS resource that's making requests.

For more information, see Working with Security Groups.

Invoke URL formatting / Private DNS

To invoke your private API, the invoke URL must be correctly formatted. The correct format depends on whether you have private DNS enabled for the interface VPC endpoint.

Private DNS disabled

Use endpoint-specific public DNS hostnames to access the private API.

Note: You can enable private DNS for your interface VPC endpoint at any time in the Amazon VPC console. In the Endpoints pane, select your interface VPC endpoint. Choose Actions, and then choose Modify Private DNS names. Select the check box for Enable Private DNS Name, and then choose Modify Private DNS names.

Private DNS enabled

Use private DNS names to access the private API.

Test to confirm that the private API endpoint domain correctly resolves to the interface VPC endpoint's IP address. Run this command from the client that's making requests to access the private API:

Note: Replace restapi-id with your private API's ID. Replace region with the AWS Region of your private API.

$ nslookup restapi-id.execute-api.region.amazonaws.com

The output should be the private IP addresses of the interface VPC endpoint.

Next, run this command:

Note: Replace vpce-id with your VPC endpoint ID. Replace region with the AWS Region of your interface VPC endpoint.

$ nslookup vpce-id.execute-api.region.vpce.amazonaws.com

Compare the IP addresses in the outputs of each command. If they're the same, then the interface VPC endpoint is being used to access the private API endpoint as expected.

External access

Cross-account access

To access your private API from an Amazon VPC in another AWS account, do the following:

  1. Create an interface VPC endpoint in the other account.
  2. Create and attach a resource policy to your private API. The policy must allow incoming traffic from the other account's VPC endpoint ID or VPC ID.

Resources in the other account's Amazon VPC (or that use its interface VPC endpoint) can use endpoint-specific public DNS hostnames to access the private API.

Note: The private API and the interface VPC endpoint in the other account must be in the same AWS Region. Accessing a private API from another Region requires a VPC peering connection.

On-premises access

From an on-premises network, connect to the VPC using AWS Direct Connect. Then, you can use endpoint-specific public DNS hostnames to access the private API.