API Key and Usage Plan Integration with AWS API Gateway

Today, we will see how we can leverage AWS API Key and Usage Plan to authenticate and restrict the number of requests to AWS REST API.

You will find the whole code and sam CLI deployment script at the end of this post. To configure directly through AWS console visit https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-usage-plans.html

What are usage plans and API keys?

A usage plan specifies who can access one or more deployed API stages and methods — and also how much and how fast they can access them. The plan uses API keys to identify API clients and meters access to the associated API stages for each key. It also lets you configure throttling limits and quota limits that are enforced on individual client API keys.

API keys are alphanumeric string values that you distribute to application developer customers to grant access to your API. You can use API keys together with usage plans or Lambda authorizers to control access to your APIs. API Gateway can generate API keys on your behalf, or you can import them from a CSV file. You can generate an API key in API Gateway, or import it into API Gateway from an external source. For more information, see Set up API keys using the API Gateway console.

Let us look at the example and steps to integrate:

Make sure to add API Auth to true in REST API code in the template.yaml to use the usage plan and API key. You can use the below two lines to set auth to true.

Resources:
  TestUsagePlanAPI:
    Type: AWS::Serverless::Api
    Properties:
      StageName: !Ref deploymentEnvironment
      Auth:
        ApiKeyRequired: 'true'

After creating the API through the YAML template, we have to add the below code to create a usage plan through the YAML template. Here Usage Plan depends on the API Stage that will be creating and integrating with so we need to add the DependsOn attribute so that it should wait till API Stage has been created.

The number of requests sends per Month and throttling can be modified accordingly.

TestAPIUsagePlan:
    Type: 'AWS::ApiGateway::UsagePlan'
    DependsOn:
      - TestUsagePlanAPI
    Properties:
      ApiStages:
        - ApiId: !Ref TestUsagePlanAPI
          Stage: !Ref deploymentEnvironment
      Description: To test usage plan and api key in REST API.
      Quota:
        Limit: 100
        Period: MONTH
      UsagePlanName: "test-usage-plan"

Once the usage plan is created, we have to create the API Key.

TestApiAccessKey:
    Type: 'AWS::ApiGateway::ApiKey'
    DependsOn:
      - TestUsagePlanAPI
    Properties:
      Name: "test-api-key"
    Description: To test usage plan and api key in REST API.
      Tags: 
       - Key: Mode
         Value: Learning
      Enabled: true
      StageKeys:
       - RestApiId: !Ref TestUsagePlanAPI
         StageName: !Ref deploymentEnvironment

Now, we have to bind the API Key to Usage Plan for which we will use the below code:

LinkUsagePlanApiKey:
    Type: "AWS::ApiGateway::UsagePlanKey"
    Properties:
      KeyId: 
       Ref: TestApiAccessKey
      KeyType: API_KEY
      UsagePlanId: 
       Ref: TestAPIUsagePlan

Once the integration is done, run your sam CLI script to deploy the API in the AWS console. Now you will be requiring the x-api-key in the header to run the API. If x-api-key is not passed, then it will throw error 403 Forbidden. If there will be too many requests for the API compare to what we have set in API requests allowed per month in the usage plan, then it will throw 429 too many requests.

We can note down the x-api-key from the AWS console in the API Key section as shown below:

Click on show in API key where you will get the API Key which can be used in the header to call the respective REST API. We can click on Usage Plan and modify the configurations accordingly.

I have created a test API in AWS which uses comprehend service to detect language. Let us see the example of calling REST API with x-api-key.

If we call the deployed API without passing x-api-key, it will give the below error:

Similarly, when we pass the x-api-key in the header to request API, we will get a successful response.

If we exceed the number of requests to API 100 per Month as we have added above in the usage plan, it will give the following error:

For automating the testing of API with multiple test cases using postman follow the article: https://hemnanirohan.medium.com/effectively-use-postman-api-testing-in-simple-steps-with-dynamic-data-in-a-file-for-test-automation-115f1a36ded4

I hope this article in some way was useful to you. To get the whole code and deployment script, visit https://github.com/Rohan009/aws_api_key_usage_plan