Skip to content

API Gateway

Amazon API Gateway is an AWS service for creating, publishing, maintaining, monitoring, and securing REST, HTTP, and WebSocket APIs at any scale. This includes handling traffic management, Cross Origin Resource Sharing (CORS) support, authorization and access control, throttling, monitoring, and API version management.

API Gateway creates RESTful APIs that:

  • Are HTTP-based.
  • Enable stateless client-server communication.
  • Implement standard HTTP methods such as GET, POST, PUT, PATCH, and DELETE.

Want to have full-duplex communication: there is a support for web-sockets too?

API Gateway creates WebSocket APIs that:

  • Adhere to the WebSocket protocol, which enables stateful, full-duplex communication between client and server.
  • Route incoming messages based on message content.

WebSocket APIs are often used in real-time applications such as chat applications, collaboration platforms, multiplayer games, and financial trading platforms.

API Gateway Architecture


  • Versions: With API Gateway, you can run multiple versions of the same API simultaneously so that you can quickly iterate, test, and release new versions. You can make changes to your API and host multiple versions of it for different users also.
  • Transform data: With API Gateway, you can also transform and validate both incoming and outgoing requests. With this feature, you can use API Gateway as a fully managed environment for transforming requests as they come into your API before they are passed to your backend.
  • Reduced Latency: API Gateway provides end users with the lowest possible latency for API requests and responses by taking advantage of the Amazon CloudFront global network of edge locations.

Custom Lambda authorizer


A Lambda authorizer (formerly known as a custom authorizer) is an API Gateway feature that uses a Lambda function to control access to your API.

A Lambda authorizer is useful if you want to implement a custom authorization scheme that uses a bearer token authentication strategy such as OAuth or SAML, or that uses request parameters to determine the caller's identity.

When a client makes a request to one of your API's methods, API Gateway calls your Lambda authorizer, which takes the caller's identity as input and returns an IAM policy as output.

Types of Lambda authorizers


There are two types of Lambda authorizers:

  • A token-based Lambda authorizer (also called a TOKEN authorizer) receives the caller's identity in a bearer token, such as a JSON Web Token (JWT) or an OAuth token. For an example application, see Open Banking Brazil - Authorization Samples on GitHub.

  • A request parameter-based Lambda authorizer (also called a REQUEST authorizer) receives the caller's identity in a combination of headers, query string parameters, stageVariables, and $context variables.

For WebSocket APIs, only request parameter-based authorizers are supported.

Using custom authorizer

It is possible to use an AWS Lambda function from an AWS account that is different from the one in which you created your API. For more information,

Authorization workflow

  1. The client calls a method on an API Gateway API method, passing a bearer token or request parameters.

What is Bearer token?

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources

  1. API Gateway checks whether a Lambda authorizer is configured for the method. If it is, API Gateway calls the Lambda function.
  2. The Lambda function authenticates the caller by means such as the following:

    1. Calling out to an OAuth provider to get an OAuth access token
    2. Calling out to a SAML provider to get a SAML assertion.
    3. Generating an IAM policy based on the request parameter values.
    4. Retrieving credentials from a database.
  3. If the call succeeds, the Lambda function grants access by returning an output object containing at least an IAM policy and a principal identifier.

  4. API Gateway evaluates the policy.

    1. If access is denied, API Gateway returns a suitable HTTP status code, such as 403 ACCESS_DENIED.
    2. If access is allowed, API Gateway executes the method. If caching is enabled in the authorizer settings, API Gateway also caches the policy so that the Lambda authorizer function doesn't need to be invoked again.

Auth using Cognito

API Gw auth using Cognito


Anatomy of URI

All of the APIs you create with API Gateway will follow the same pattern as you see in the invoke URL above, reflecting the ID of the API and the Region in which you created it, followed by a stage, and then the resource and resource path you want to expose.


HTTP Endpoint

HTTP integration endpoints are useful for public web applications where you want clients to interact with the endpoint. This type of integration lets an API expose HTTP endpoints in the backend.

Lambda Fn

When you are using API Gateway as the gateway to a Lambda function, you’ll use the Lambda integration. This will result in requests being proxied to Lambda with request details available to your function handler in the event parameter, supporting a streamlined integration setup.

AWS Service

AWS Service is an integration type that lets an API expose AWS service actions. For example, you might drop a message directly into an Amazon Simple Queue Service (Amazon SQS) queue.


Mock lets API Gateway return a response without sending the request further to the backend. This is a good idea for a health check endpoint to test your API. Anytime you want a hardcoded response to your API call, use a Mock integration.

Was this page helpful?