August 7, 2023

Unlocking the Power of API Gateway: Maximizing API Offerings with Usage Plans and API Keys

The best time to establish protocols with your clients is when you onboard them.


Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique. Duis cursus, mi quis viverra ornare, eros dolor interdum nulla, ut commodo diam libero vitae erat. Aenean faucibus nibh et justo cursus id rutrum lorem imperdiet. Nunc ut sem vitae risus tristique posuere.

AWS API Gateway is a fully managed service provided by Amazon Web Services (AWS) that enables developers to create, publish, monitor, and secure APIs at any scale. Furthermore, AWS API Gateway seamlessly integrates with other AWS services, such as AWS Lambda, AWS Step Functions, and Amazon DynamoDB, enabling developers to build serverless architectures and create powerful API-driven applications.

AWS API Gateway introduced usage plans in October 2015. Usage plans are a feature that allows API owners to manage and control access to their APIs by defining usage limits and associated quotas for individual API keys or client IDs. With usage plans, you can provide your API as an offering. For example, if you had some AI-powered Backend you can take that API into the market by sorting the clients under usage plans (normal, premium..). This Article contains four sections.


The reader should understand what a lambda function is, as well as how to create a function in AWS Lambda and an API in API Gateway.

  1. The first section is about the basic terminology required to understand the article.
  2. In section 2, we will create a basic Lambda function and associate it with the API gateway.
  3. In section 3, we are going to create a Usage plan and API keys, and then we associate them with the API we created.
    Scene Description:
    * We are providing our API as an Offering, which does basic Mathematical calculations (sounds very simple but it’s a good place to start.)
    * Every Individual client can only use our offering 5 times per day.
    * A client who accesses more than the quota allotted (5 in this scenario) is responded with an HTTP status code of 429 (Too Many Requests).
  4. Finally, in section 4, we will see some Important points in using API Gateway Usage plans.


Glossary: Usage Plan, API key, throttling limit, quota limit, burst requests.

Usage Plan:

Usage plans in API Gateway enable you to set limits on the number of requests an API key or client can make within a specified time period. These limits are typically set as a steady-state rate limit, which defines the maximum number of requests allowed per second, minute, or hour.

API key:

When using usage plans, API keys can be associated with specific plans, allowing you to control access and set usage limits on a per-key basis.

Throttling limit:

The throttling limit refers to the maximum number of requests that an API key or client is allowed to make within a specified time period. It is a mechanism for controlling the rate at which requests are processed by an API.

Burst Requests:

Burst requests provide some flexibility by allowing occasional bursts of traffic that exceed the steady-state rate limit. It allows a certain number of requests to be processed immediately, even if they exceed the defined rate limit, instead of being throttled or rejected.

Quota limit:

A quota limit sets the target maximum number of requests with a given API key that can be submitted within a specified time interval.


  1. Create a lambda with the name demo-lambda-usage-plan with node js environment.

2. Get the code from here:

3. From the API gateway console create an API with Name demo-API-usage-plan in the same region where Lambda is created.

4. Under this API create a New Resource named /usageplanOffering.

5. Create a POST method under this resource and establish a proxy integration between the lambda you created (demo-lambda-usage-plan) previously and this method.

6. Finally, deploy the API to the stage usage-plan-test.



Now, let’s create an API Key and Usage Plan.

  1. From API Gateway Console → API Keys → Create a New API Key with name “testApikey”

2. From API Gateway Console → Usage Plans → Create a New Usage plan named “demo-usage-plan”.

3. Tick Enable Throttling & Quota and configure the fields as per your requirements. Here we are providing a Quota of 5 requests per day. (please refer to the keywords section in this article). Now click “Next”.

4. Here we need to associate the API (demo-API-usage-plan), API Stage(usage-plan-test), resource (/usageplanoffering), and Method to the usage plan(demo-usage-plan) and click “Next”.

5. Select the API Keys tab and associate the API Key we created (testApikey) previously.

6. From the Usage option you can view the graph of the number of invocations made by this API Key.

7. From API Gateway Console → Resources → POST Method pane → Method Request → change the status of API Key required to true.

8. From API Gateway Console → Stages, again deploy the API to stage (usage-plan-test).

9. Now copy the method invocation URL and paste it in Postman.

10. From API Gateway Console → API KEYS, select testApikey and copy the API key.

11. Now put this API KEY in Headers with a key name “X-API-Key”.

12. Now use the request body as shown and make a request. The API will respond with a status of 200 for the first 5 invocations. For the sixth invocation, it will respond with a status code of 429 (Too Many Requests).

13. To view the invocations count visit Api gateway console → usage Plans → select (demo-usage-plan) → API Keys tab → click usage.

14. Using the export option you can export to JSON or CSV.


Important points to remember:

  1. You can leverage lambda authorizers along with API keys and usage plans to control access to your API Gateway endpoints.
  2. API key values must be unique.
  3. If you try to create two API keys with different names and the same value, API Gateway considers them to be the same API key.
  4. An API key can be associated with more than one usage plan.
  5. A usage plan can be associated with more than one stage.
  6. However, a given API key can only be associated with one usage plan for each stage of your API.

August 7, 2023
min read
Subscribe to our newsletter
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
Share this article

More articles

Connect with us

Get more updates and further details about your project right in your mailbox.

Thank you!
Oops! Something went wrong while submitting the form.