Protect Your API With Authorization and Usage Plans in AWS API Gateway

If you haven’t read our first article on severless computing with AWS API Gateway, you can find it here.

AWS API Gateway is a fully managed service that enables developers to create, publish, maintain, monitor, and secure APIs (Application Programming Interface) for their applications at any scale.

While the initial setup of an API with AWS API Gateway is fast and easy, it is integral to protect and secure the access to services and data it provides to not give way to unauthorized and potentially malicious access.

One of the key features of API Gateway is the ability to protect your API with authorization and usage plans, ensuring that your API is only accessed by authorized users and is not overwhelmed by excess traffic. In this article, we will explore the different options available for authorization and usage plans in API Gateway and how to configure them.

Authorization is an optional feature of API Gateway. You can choose to skip auth in your API entirely, or you can opt to handle authorization in your integration backend. That said, if authorization is wanted in your API, putting it in API Gateway can be a smart choice for a number of reasons:

  • It consolidates your authentication logic to a single place
  • It protects your downstream integration from unauthorized requests, saving you costs and/or load on your resources
  • It can be cached, reducing the number of hits on your authentication service

Within this authorization step, there are two options that apply — the authorization check and the check based on API key.

Authorization with custom authorizers, Cognito, or IAM

The most common authorization is an actual authorization check, the request information can be checked to identify the caller of an API – based on either an HTTP header or a querystring – and either allow or reject the request based on whether the caller has permission to invoke theAPI. There are three main methods for configuring an authorization check in API Gateway:

Using IAM permissions via signed HTTP requests:

This method allows you to use AWS IAM policies to authorize API requests. When using this method, you will need to sign the HTTP requests with your AWS access key and secret key. This can be done using the AWS Signature Version 4 signing process.

Using tokens from a Cognito User Pool:

If you are using Cognito User Pools for your authentication needs, you can use tokens from the user pool to authorize API requests. With this method, you will need to configure the required scopes needed for a particular API endpoint.

Writing your own custom logic in a Lambda custom authorizer:

If you need more fine-grained authorization needs, you can write your own custom logic in a Lambda function and use it as a custom authorizer for your API Gateway. With custom authorizers, you have complete control over the authorization process and can run any logic you need to authenticate and authorize the caller. You can also inject additional context into the request based on the identity of the caller.

For a user-facing API, the latter two options are most commonly used.

If you are already using Cognito User Pools for your authentication needs, integrating them with API Gateway can be a straightforward and convenient option. You can configure the required scopes for a particular API endpoint without having to write any custom logic.

On the other hand, if you are not using Cognito User Pools or if you need more granular authorization controls, you can use Lambda custom authorizers. With custom authorizers, you have complete flexibility to implement any authentication and authorization logic that you need. You can also add additional context to the request based on the identity of the caller.

Source: Example architecture diagram of adding authentication (AWS Cognito) and authorization (AWS Lambda Custom Authorizer) services to the AWS API Gateway. For an in-depth example of an API Gateway Authorizor setup see this article from AWS: Building fine-grained authorization using Amazon Cognito, API Gateway, and IAM.

API keys and usage plans

The API key check is part of the authorization process in API Gateway. You can configure the service to require API keys to be included with every request. These keys are passed in the x-api-key header, and requests without them will be rejected. While API keys are often included in the authorization process, they should not be considered a primary method of authorization. They are not a precise way to identify and authorize users.

API keys are most commonly used for rate limiting and throttling users. AWS provides usage plans that allow you to associate API keys with specific limits. These plans can be configured with throttling limits (the number of requests per second allowed) and quota limits (the maximum number of requests over a certain period of time).

Throttling limits can help prevent a caller from overloading your downstream resources, while quota limits can be used to enforce limits on paid APIs or specific clients. Quota limits allow you to set a maximum number of requests over a particular time period, such as a day, a week, or a month. This allows you to enforce limits on a particular client. This comes in handy, if you are providing a paid API where a user gets a certain number of calls per month.

By default, usage plans are limited to 300 per account per region, but you can request an increase if necessary.


In summary, API Gateway provides a range of options for protecting your API with authorization and usage plans. While it is not necessary to include any form of authorization on your API, implementing authorization in API Gateway can provide protection, and save money and resources on your downstream integrations. There are three options for authorizing requests: using Cognito User Pools, AWS IAM, or a Lambda custom authorizer. API keys can also be used to throttle specific users by setting limits on their requests. The authorization check is run before the API key check. You have the option to use either, both, or neither of these checks in your API.

More Reading

Post navigation