Controlling API Usage with API Keys and Usage Plans on AWS API Gateway

Contolling API Usage with API Keys and Usage Plans on AWS API Gateway

AWS API Gateway provides us to develop our own RESTful APIs and trigger AWS Lambda functions upon HTTP requests. I often use this architecture in my serverless applications and developed many APIs for my clients. With the help of API Keys and Usage Plans, we can define maximum request quotas and manage request rates while sharing our API with others.

Although API keys can never be considered as a full security measure as we often store these keys in client applications calling the API, usage plans can provide us to limit the API access and be sure that usage does not exceed tresholds we define.

API Gateway and AWS Lambda

We talked about AWS Lambda functions before in this blog. As you can remember, AWS Lambda allows us to write our own functions using Python, NodeJS or another supported programming language we choose without maintaining any servers. Lambda functions suits well to use in RESTful APIs where we create Lambda functions to make CRUD actions on a DynamoDB or RDS database or even send data to a datawarehouse.

In API Gateway, we create our API, define our resources such as users and methods such as POST under this resource. Then, we integrate this method with an AWS Lambda function and make whatever we want when an HTTP POST request is made to /users endpoint.

We use API Gateway stages to deploy our APIs to different environments. For example, we can define a test stage for test environment and prod for production.

Although Lambda is not the only integration supported by API Gateway, I will use this architecture to describe what we are trying to do in this post.

Should API Keys be used for authorization?

API keys should not be considered as an authorization mechanism. We distribute API keys to developers and they use in their applications. Hence, we cannot be sure that these keys are stored in safe environments. If developers are using API keys to make request from a hardened webserver, we may consider these keys as stored in a safe environment such as in environment variables. Even so, we can never be sure of this unless we are the sole user of our API keys.

In a serverless architecture, such as an Angular app making HTTP requests to our API, we cannot predict where our keys are stored. Our API keys are distributed to all clients in this scenario. It is like storing our credentials in client application which is opposite of the definition of secure.

To sum up, API Keys are not for authorization. They are for controlling request rates and analyzing the calls made. They are actually very useful under these concepts. For authorization, you should consider AWS Lambda custom authorizers or Amazon Cognito which are out of the scope of this blog post.

How are usage plans created?

There are two terms when defining a usage plan on AWS API Gateway. These are throttling and quota.

Throttling is about controlling the request rate in a second and it is implemented using a Token Bucket model. In the rate section we define how many request on average in a second to be considered as 1 token. In burst section we define a total limit as the number of maximum tokens available in this bucket. When a request made, if there are tokens remaining in this limit the request is allowed; otherwise, rejected.

Quota is about limiting the number of request per a specific interval such as day, week or month. If this quota is used in this time interval, no more requests are accepted.

From business perspective, you can offer different usage plans to your customers such as “silver”, “gold” and define different throttling rates and quotas for these plans. From technical perspective, usage plans provide us to know the maximum rate our infrastructure should handle and plan accordingly.

Usage plans are defined globally for all APIs in an API Gateway service in a region. To create a usage plan, go to API Gateway console and click on “Usage Plans” from the left menu and click on “Create”.

Usage Plan creation on API Gateway

As you can see below, I created fictional Bronze, Silver and Gold subscription plans to provide my API services to my fictional clients.

Multiple Usage Plans on API Gateway

How are usage plans associated with APIs?

We associate usage plans with the stages of our APIs. This allows us to define different usage plans for different stages such as development, test, beta and production. We can associate during usage plan creation or from Usage Plan details on API Gateway console.

Usage Plan association with an API

Here, there is an exclamation mark to warn that not all API endpoints are configured to use API keys. Also, this is not ideal, because I added test stage of one of my APIs. I did this to show that we can associate different stages of different APis. Let’s go to method’s Method Request which is the gate keeper of the endpoint and make API Key usage reuired.

Using API key in an API Gateway method

Please do not forget to deploy the API after saving this change. Otherwise, it would not take effect.

Creating API Keys and associating with a Usage Plan

The last thing we need to do is creating API keys for our clients and associating them with usage plans. For example, let’s say that we have client named Joe Black who bought Bronze subscription for our API service. First we need to create an API Key from API Gateway Console by going to API Keys section and selecting Create API Key from Actions.

Creating an API key on API Gateway Console

After saving, we can associate this API key with a usage plan by clicking on Add to Usage Plan.

Adding API key to a Usage Plan on API Gateway Console

And the result is below. As you can see, AWS Console also shows us which stages this plan is associated with.

API key after added to a Usage Plan on API Gateway Console

The last thing we need to do is sharing this API Key with Joe. We can reveal it by clicking on Show next to API Key as below.

Revealing API key on API Gateway Console

Now, Joe needs to provide this API key in x-api-key header in his requests to the APIs. Otherwise, unfortunately his requests will fail. We can disable this key in the future from this section when Joe’s subscription ends. We can also automate this process using AWS Lambda and AWS SDKs.


API Gateway is a useful service for creating our own APIs. From business side, usage plans and API Keys allow us to offer different plans to our customers purchasing our services. From technical side, they allow us to control and analyze the usage and plan our resources accordingly. However, API keys should not be used as an authorization method.

I hope this post gave you an idea about how you can use API keys and usage plans on AWS API Gateway.

Thanks for reading!


Emre Yilmaz

Independent AWS Consultant & Founder @ Shikisoft



View Shikisoft's online courses

Join Our AWS Courses!

Would you like to learn AWS services like AWS CodePipeline and AWS CloudFormation in detail with hands-on examples?

Find more details on our available courses and enroll in them with a discount!

View Our Online Courses


Subscribe to this blog's RSS feed