AWS API Gateway lets us develop our own RESTful APIs and trigger AWS Lambda functions upon HTTP requests. I often use this architecture in 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.
API keys can never be considered a complete security measure as we often store these keys in client applications calling the API. Still, usage plans can help us limit the API access and ensure that usage does not exceed the thresholds 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 functions using Python, NodeJS, or another supported programming language we choose without maintaining any servers. Lambda functions suit 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 data warehouse.
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 the /users endpoint.
We use API Gateway stages to deploy our APIs to different environments. For example, we can define a test stage for the 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 these API keys in their applications. Hence, we cannot be sure that they will be stored in safe environments. If developers use API keys to make requests from a hardened web server, we may consider these keys 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.
We cannot predict where our keys are stored in a serverless architecture with a front end, such as an Angular app making HTTP requests to our API. Our API keys are distributed to all clients in this scenario. It is like storing our credentials in a client application which is the opposite of the definition of secure.
To sum up, API Keys are not for authorization. They can help us control request rates and analyze the calls made, and they may be handy with these features. For authorization, you should consider AWS Lambda custom authorizers, IAM authorization, 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 requests on average in a second are to be considered as one token. In the burst section, we define a total limit as the number of maximum tokens available in this bucket. When a request is made, if there are tokens remaining in this limit, the request is allowed; otherwise, rejected.
Quota is about limiting the number of requests per a specific interval such as day, week, or month. No more requests are accepted if this quota is used in this time interval.
From a 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 a 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 the API Gateway Console, 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 the 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 the 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 the method’s Method Request, which is the gatekeeper of the endpoint, and make the API Key usage required.
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 a client named Joe Black who bought a Bronze subscription for our API service. First, we need to create an API Key from API Gateway Console by going to the API Keys section and selecting Create API Key from Actions.
After saving, we can associate this API key with a usage plan by clicking on Add to Usage Plan.
The result is below. As you can see, AWS API Gateway 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 the API Key.
Now, Joe needs to provide this API key in the 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.
Conclusion
API Gateway is a valuable service for creating our own APIs. From the business side, usage plans and API Keys allow us to offer different plans to our customers purchasing our services. From the technical side, they enable us to control and analyze the usage and plan our resources accordingly. However, you should not use API keys in your APIs for authorization.
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!
