Menu
Amazon API Gateway
Developer Guide

Create and Use API Gateway Usage Plans

After you create, test, and deploy your APIs, you can extend them as product offerings for your customers. You can provide usage plans to allow specified customers to access selected APIs at agreed-upon request rates and quotas that can meet their business requirements and budgetary constraints.

What Is a Usage Plan?

A usage plan provides access to one or more deployed API stages with configurable throttling and quota limits enforced on individual client API keys. API callers are identified by API keys that can be generated by API Gateway or imported from external sources. The throttling prescribes the request rate limits applied to each API key. The quotas are the maximum number of requests with a given API key submitted within a specified time interval. Individual API methods can be configured to require API key authorization based on usage plan configuration. An API stage is identified by an API identifier and a stage name.

Note

Throttling and quota limits apply to requests for individual API keys that are aggregated across all API stages within a usage plan.

How to Configure a Usage Plan?

The following steps outlines how you, as the API owner, configure a usage plan for your customers.

To configure a usage plan

  1. Create one or more APIs, configure the methods to require an API key, and deploy the APIs in stages.

  2. Generate API keys and distribute the keys to app developers (your customers) using your APIs.

  3. Create the usage plan with the desired throttle and quota limits.

  4. Associate selected API stages and API keys to the usage plan.

Callers of the API must supply an assigned API key in the x-api-key header in requests to the API.

Note

To include API methods in a usage plan, individual API methods must be configured to require an API key. For user authentication and authorization, do not use API keys. Use an IAM role, a custom authorizer or an Amazon Cognito user pool.

The following sections provide detailed instructions for these tasks.

Set Up API Keys Using the API Gateway Console

To set up API keys, do the following:

  • Configure API methods to require an API key.

  • Create or import an API key for the API in a region.

Before setting up API keys, you must have created an API and deployed it to a stage.

For instructions on how to create and deploy an API using the API Gateway console, see Creating an API in Amazon API Gateway and Deploying an API in Amazon API Gateway, respectively.

Require API Key on a Method

The following procedure describes how to configure an API method to require an API key.

To configure an API method to require an API key

  1. Sign in to the AWS Management Console and open the API Gateway console at https://console.aws.amazon.com/apigateway/.

  2. In the API Gateway main navigation pane, choose Resources.

  3. Under Resources, create a new method or choose an existing one.

  4. Choose Method Request.

  5. Under the Authorization Settings section, choose true for API Key Required.

  6. Select the check-mark icon to save the settings.

  7. Deploy or redeploy the API for the requirement to take effect.

If the API Key Required option is set to false and you do not execute the steps above, any API key associated with an API stage will not used for the method.

Create an API Key

If you have already created or imported API keys for use with usage plans, you can skip this and the next procedure.

To create an API key

  1. Sign in to the AWS Management Console and open the API Gateway console at https://console.aws.amazon.com/apigateway/.

  2. In the API Gateway main navigation pane, choose API Keys.

  3. From the Actions drop-down menu, choose Create API key.

    
                                    Create API keys for usage plans
  4. In Create API Key, do the following:

    1. Type an API key name (e.g., MyFirstKey) in the Name input field.

    2. Choose Auto Generate to have API Gateway to generate the key value or choose Custom to enter the key manually.

    3. Choose Save.

    
                                    Create API keys for usage plans
  5. Repeat the preceding steps to create more API keys, if needed.

Import API Keys

The following procedure describes how to import API keys to use with usage plans.

To import API keys

  1. In the main navigation pane, choose API Keys.

  2. From the Actions drop-down menu, choose Import API keys.

  3. To load a comma-separated key file, choose Select CSV File. You can also type the keys manually. For information about the file format, see API Gateway API Key File Format.

    
                                    API usage plan entities
  4. Choose Fail on warnings to stop import when there is an error, or choose Ignore warnings to continue to import valid key entries when there is an error.

  5. To start importing the selected API keys, choose Import.

Now that you have set up the API key, you can proceed to create and use a usage plan.