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
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 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”.
As you can see below, I created fictional Bronze, Silver and Gold subscription plans to provide my API services to my fictional clients.
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.
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.
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
After saving, we can associate this API key with a usage plan by clicking on
Add to Usage Plan.
And the result is below. As you can see, AWS Console also shows us which stages this plan is associated with.
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.
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!