Amazon API Gateway private integrations let an API expose services that remain inside an Amazon VPC. API clients interact with API Gateway, while API Gateway reaches the backend through a VPC link V2. That pattern is useful for ECS services, internal load balancers, private application tiers, and other HTTP resources that should not become public simply because they need an API front door.
Inside the AWS Architecture and Operations cluster, private integration is a network and ownership decision as much as an API configuration choice. Authorization, the VPC link, load balancer or Cloud Map target, TLS, stage-path mapping, and backend health all have to line up for the request to succeed.
The existing API security fundamentals article remains relevant because a private backend still needs explicit authorization and resource-level controls.
VPC links V2 are the current integration path for new designs
API Gateway now supports VPC links V2 for both HTTP APIs and REST APIs. For REST APIs, VPC links V1 remain a legacy integration type and AWS recommends not creating new V1 links. V2 removes the older REST requirement to front every integration with a Network Load Balancer and supports Application Load Balancers as targets.
The link creates and manages elastic network interfaces in the selected VPC subnets. That means subnet selection, security groups, route reachability, and target health all become part of the API path even though the client never sees those details.
VPC links can be reused across compatible APIs and integrations, but sharing them also creates a common dependency. A change to the link or its subnets can affect more than one API.
HTTP APIs and REST APIs do not have identical private-integration options
HTTP APIs can connect through VPC links V2 to an Application Load Balancer, Network Load Balancer, or resources registered with an AWS Cloud Map service. Cloud Map integration lets API Gateway discover healthy service instances and distribute traffic across the returned IP addresses and ports.
REST APIs with VPC links V2 support Application Load Balancer and Network Load Balancer targets, but AWS documentation currently states that Cloud Map private integration is not supported for REST APIs.
This difference should be part of API-type selection when service discovery is a requirement. Choosing REST or HTTP API only by feature familiarity can create unnecessary load-balancer infrastructure later.
The API, VPC link, and private target must share an AWS account
AWS currently requires the API, VPC link, and private integration resource to be owned by the same AWS account. That constraint matters in multi-account platform designs where application teams, networking teams, and shared services may live in separate accounts.
If the backend is cross-account, the architecture may need a different exposure pattern, account placement, or service-sharing mechanism. Private integration should not be assumed to cross account boundaries just because the VPCs themselves can communicate.
The account boundary should therefore be decided before the platform team standardizes private integration as the only internal API pattern.
Stage names can leak into the backend path if mapping is not explicit
For private integrations, API Gateway includes the stage portion of the API endpoint in the request it sends to the backend by default. A request to the test stage can therefore reach the target as test/route-path.
That behavior is easy to miss when the backend expects a path beginning directly at the resource. API Gateway supports parameter mapping so the request path can be overwritten with the original route path instead.
Path behavior should be part of contract testing, especially when one backend is used by several stages or APIs.
HTTPS requires an explicit secure-server configuration
Private integration traffic uses HTTP by default. To use HTTPS, configure a secure server name or the relevant TLS configuration so API Gateway negotiates TLS to the backend.
This is separate from TLS between the client and API Gateway. An externally HTTPS API can still use plaintext HTTP on the private integration unless the backend side is configured for TLS.
Certificate name, backend listener, and target configuration should be tested together so the team knows where encryption begins and ends.
Idle VPC links can become inactive
A current VPC link V2 that receives no traffic for 60 days can transition to an INACTIVE state. API Gateway removes the link’s network interfaces while it is inactive. When traffic resumes, API Gateway reprovisions the interfaces, and requests that depend on the link can fail during that recovery period.
This is important for disaster-recovery APIs, seasonal applications, and standby environments that may intentionally receive no traffic for long periods. A design that assumes the link will always be immediately warm can create a surprise during the first real request after months of inactivity.
Operational testing should include dormant paths where that behavior matters.
Load balancer health and service discovery become API dependencies
For ALB and NLB integrations, API Gateway sends traffic to the specified listener, and the load balancer then selects healthy targets. For Cloud Map integrations with HTTP APIs, API Gateway calls service discovery and distributes requests across healthy instances.
That means API Gateway availability is only one layer. A healthy API stage can still return errors when target groups are empty, health checks fail, or Cloud Map registration is stale.
Dashboards should therefore include backend health and response status alongside API Gateway latency and error metrics.
Private integration should not be confused with a private API endpoint
A private integration describes how API Gateway reaches the backend. A private API endpoint describes how clients reach API Gateway. The two can be combined, but they solve different boundaries.
A public regional API can use a private integration to keep the backend inside the VPC. A private REST API can restrict client access to VPC endpoints. The architecture should decide independently whether clients and backends are public or private.
This distinction helps security reviews avoid statements such as “the API is private” when only the integration side is private.
Operational readiness means testing the entire request path
Production tests should cover authorization, client-to-API TLS, route mapping, VPC link state, backend TLS, target health, timeout behavior, and the backend’s own authorization. A synthetic request that exercises the real private target is more useful than an API Gateway control-plane check alone.
Private integration is valuable because it lets teams keep application services off the public internet while still using API Gateway as a managed front door. It is successful when that convenience does not hide the network and ownership dependencies behind the API.
Subnet selection deserves deliberate design. The VPC link creates managed network interfaces in the selected subnets, so those subnets need enough IP capacity and the correct route reachability to the target. Reusing undersized application subnets can create pressure that is hard to diagnose because the client only sees API errors while the underlying issue is address exhaustion or an unreachable backend path.
Security groups should be reviewed from the perspective of the actual connection source. The target load balancer and downstream tasks or instances need rules that permit the traffic path created by the VPC link and load balancer. Broad CIDR rules may work quickly but weaken least privilege and make later network changes harder to reason about.
For ALB-backed ECS services, deployment health should be observed end to end. A new task revision can be registered in the target group before it is ready to serve the API contract, or can fail health checks and leave too few healthy targets. API Gateway availability can remain green while the target group becomes the real point of failure. Synthetic requests should therefore test a representative route through the actual integration.
Timeouts should be aligned across API Gateway, the load balancer, the application server, and any downstream services. If the backend can take longer than the API layer allows, the client may receive a timeout even though the backend continues working. For non-idempotent operations, that can create duplicate work when the client retries. The application contract should specify whether long-running work is synchronous, asynchronous, or accepted for later completion.
Private integration also changes how logs should be correlated. API Gateway request IDs, load-balancer access logs, ECS or application logs, and downstream trace identifiers should be tied together so operators can follow one request across the public API boundary into the private service. Without correlation, incidents are often split between API and network teams even though the failure is one end-to-end path.
Infrastructure-as-code should own the VPC link, integration URI, route mapping, and backend listener relationship. Manual changes in the console can create a configuration that works but cannot be reproduced in another environment. Private integration is most maintainable when development, staging, and production share the same declared pattern with only environment-specific identifiers and capacity values changing.
Cross-environment sharing should be constrained. Reusing one VPC link across many APIs can reduce administrative overhead, but it also couples their failure and change domains. A platform team may prefer one link per environment or business boundary so a security-group or subnet change in development cannot accidentally affect production integrations.
Deployment tests should include the stage-path rewrite and TLS configuration because both are easy to get right in one console test and wrong in infrastructure-as-code promotion. The production acceptance test should call the external API, verify the exact backend path, confirm the expected Host and TLS behavior, and trace the request to the target.
Private integrations are also a good place to define ownership boundaries. The API team owns the public contract and API Gateway configuration; the platform team may own the VPC link; the application team owns target health and response semantics. Runbooks should name these owners so an incident does not bounce between teams while clients are failing.
