Amazon API Gateway · Managed API front door

Authorize and control every API call at a single point

API Gateway is the front door for REST, HTTP, and WebSocket APIs. It authorizes requests, throttles traffic that exceeds limits, and forwards calls to Lambda or to services inside a VPC. You can also build private APIs that are callable only from within a VPC.

Compare API types See the private API design
Request · prod stageHTTP API
GET /orders/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...
Accept: application/json
AuthorizerJWT verified
ThrottlingWithin limits
RouteGET /orders/{id}
IntegrationVPC link → ALB
200 OKOver the limit429 Too Many Requests
99.95%

Monthly availability SLA

10,000

Default requests per second per account per Region (adjustable)

10 MB

Maximum REST and HTTP API payload (excluding REST response streaming)

2 h

Maximum WebSocket connection duration

Why API Gateway

More APIs call for a common gateway

When every service implements its own authorization, throttling, and logging, policies drift apart and operational overhead grows. Apply common policies at the gateway and let backends focus on business logic.

Secure

Authorize at the gateway

Verify callers with IAM, a Lambda authorizer, Cognito, or JWT before requests reach the backend.

Control

Traffic limits

Apply token bucket limits per account, per stage and method, and per client.

Private

Private paths

Expose APIs only to VPCs and on-premises networks through interface VPC endpoints, and reach private backends through VPC links.

API types

REST, HTTP, WebSocket API

HTTP APIs offer a reduced feature set at a lower price, while REST APIs include management features such as private endpoints, API keys, caching, and AWS WAF. Use WebSocket APIs for two-way real-time communication.

Comparison of API Gateway API types
TypeCommunication modelAuthorizationKey featuresBest for
REST API Request · response IAM, Cognito user pool, Lambda authorizer, resource policy Edge-optimized · Regional · Private endpoints, API keys and usage plans, caching, AWS WAF, request validation, canary deployments, response streaming Private APIs, per-client limits, fine-grained request transformation
HTTP API Request · response IAM, JWT authorizer (including Cognito), Lambda authorizer Regional endpoint, automatic deployments, AWS Cloud Map private integration Simple proxy APIs in front of Lambda or HTTP backends
WebSocket API Persistent two-way connection IAM, Lambda authorizer ($connect route) $connect · $disconnect · $default routes, route selection expression, server push via @connections Chat, notifications, real-time dashboards

Authorization

Three ways to verify callers

Choose based on whether the caller is a workload with AWS credentials or an app holding a user token.

IAMSigV4

IAM permissions

IAM policies evaluate requests that callers sign with SigV4. REST APIs can also restrict source VPCs, VPC endpoints, and accounts with a resource policy.

SigV4IAM policyResource policyaws:SourceVpce
LambdaCustom

Lambda authorizer

A Lambda function inspects a token in a header or query string and returns whether to allow the request. Use it for in-house authentication schemes or JWT validation on REST APIs.

TokenRequest parametersREST · HTTP · WebSocket
JWTOIDC

Cognito · JWT authorizer

REST APIs use a Cognito user pool authorizer; HTTP APIs use a JWT authorizer. The HTTP API JWT authorizer validates tokens from OIDC issuers, including Cognito.

Cognito user poolJWT issuerAudienceScopes

Features

Key features

Private endpoint

Private API

A REST API that can be called only through an execute-api interface VPC endpoint. Traffic never traverses the internet, and on-premises clients can call it over Direct Connect.

Private domain

Private custom domain

Give a private API an internal domain name managed with an ACM certificate. Share it with other accounts through AWS RAM; consumer accounts associate it with their VPC endpoints.

Throttling

Tiered limits

Rate and burst limits apply at the AWS Region, account, stage and method, and client levels. Requests over the limit receive a 429 response.

API management

Usage plan · API key

On REST APIs, identify clients with API keys and set per-client request limits and usage quotas per period.

Custom domain

Custom domains · mTLS

Map multiple APIs and stages to a domain such as api.example.com. Both REST and HTTP APIs can verify client certificates with mutual TLS. REST APIs can split requests across APIs and stages with header-based routing rules, and can also apply mTLS to backend integrations with an ACM certificate.

Private integration

VPC link

Both REST and HTTP APIs connect directly to an ALB in private subnets through VPC link v2, and NLBs are also supported. HTTP APIs can also route to services registered in AWS Cloud Map.

Streaming

REST API response streaming

Stream responses from Lambda, HTTP proxy, and private integrations to clients as they are generated. Time to first byte improves, integration timeouts extend up to 15 minutes, and responses can exceed 10 MB.

Developer portal

API Gateway Portals

A managed developer portal that discovers the APIs in your account, generates documentation, and publishes them to internal and external developers grouped as PortalProducts. It provides access control and usage analytics based on CloudWatch RUM.

AI agents

MCP proxy

Connect existing REST APIs to Amazon Bedrock AgentCore Gateway and expose them as MCP-compatible endpoints. AI agents discover and call the APIs as tools without any application changes.

Integration types

How requests reach the backend

Integration types for REST APIs. Proxy types pass requests and responses through unchanged; non-proxy types transform them with mappings.

AWS_PROXY

Lambda proxy

Passes the entire request to a Lambda function. This is the recommended way to invoke Lambda.

HTTP_PROXY

HTTP proxy

Passes requests and responses to and from an HTTP endpoint unchanged. Use it with a VPC link for private backends.

AWS · HTTP

Mapped integration

Calls an AWS service action or an HTTP endpoint, with integration request and response mappings that you define.

MOCK

Mock

API Gateway responds without calling a backend. Use it for testing and parallel development.

Reference architecture

A private API open only to VPCs and on-premises

The private REST API is called only through an execute-api interface endpoint, and a resource policy specifies which VPC endpoints are allowed. On-premises clients come in over Direct Connect and resolve names through a Resolver inbound endpoint.

API Gateway private API reference architecture On-premises corporate clients connect to the consumer VPC over Direct Connect and resolve the API name through a Route 53 Resolver inbound endpoint. Applications in the consumer VPC and on-premises clients call the private REST API through an execute-api interface endpoint. The private REST API accepts requests only from VPC endpoints allowed by its resource policy, and either proxies to a Lambda function or forwards through a VPC link to an ALB or NLB in private subnets. ON-PREMISES AWS REGION CONSUMER VPC API GATEWAY BACKEND Corp clientCorporate DNS Application10.0.1.0/24 Interface endpointexecute-api · Private DNS Resolver inboundOn-prem name resolution Private REST APIaws:SourceVpce policy VPC linkVPC link v2 LambdaAWS_PROXY ALB · NLBPrivate subnets DX DNS query HTTPS
Direct Connect (on-premises calls) API call path DNS query → Arrows: request and query direction (responses return along the same path)

On narrow screens, swipe the diagram sideways.

Getting started

Steps to launch a private API

  1. STEP 1

    Create the endpoint

    Create an execute-api interface endpoint in the consumer VPC and allow port 443 in its security group.

  2. STEP 2

    Create the private API

    Create a REST API with the Private endpoint type.

  3. STEP 3

    Resource policy

    Specify the allowed VPC endpoints with the aws:SourceVpce condition.

  4. STEP 4

    Integrate · deploy

    Attach a Lambda or VPC link integration to each method and deploy to a stage.

  5. STEP 5

    Test calls

    Call the API from inside the VPC; on-premises clients resolve its name through the Resolver inbound endpoint.

Pricing

Cost components

API Gateway has no minimum fees or commitments. Cost is based on API calls received, WebSocket messages and connection minutes, and data transferred out. How the Free Tier applies depends on when the account was created.

API Gateway billing items
Billing itemBilling basisNotes
REST API callsPer million API calls received, tiered by usageFree Tier-eligible accounts get 1 million calls per month free. With response streaming, each 10 MB of response counts as one request.
HTTP API callsPer million API calls receivedFewer features than REST APIs at a lower unit price. Free Tier-eligible accounts get 1 million calls per month free.
WebSocket APIPer million messages sent and received (metered in 32 KB increments) plus connection minutesControl frames such as ping and pong are not metered.
API cacheHourly rate by the selected REST API stage cache sizeApplies only to stages with caching enabled.
PortalMonthly fee per portal (includes 10 PortalProducts), plus a monthly fee per additional PortalProductProrated for partial months.
Data transferPer GB of data transferred out, at EC2 data transfer ratesPrivate APIs incur no data transfer out (DTO) charges from AWS.
Private API endpointHourly rate per AZ for the execute-api interface VPC endpoint, plus per GB of data processedBilled by AWS PrivateLink.
Related servicesLambda invocations, CloudWatch Logs, AWS WAFBilled separately by each service.

Rates vary by Region and usage. See the API Gateway pricing page for current rates.

Next step

Let's design the right gateway for your APIs

Bring your callers, exposure scope, expected traffic, and backend locations, and we will review API types, authorization, and network paths together.

Open the service page Read the Developer Guide