Usage plans and API keys for REST APIs in API Gateway
After you create, test, and deploy your APIs, you can use API Gateway usage plans to make them available as product offerings for your customers. You can configure usage plans and API keys to allow customers to access selected APIs, and begin throttling requests to those APIs based on defined limits and quotas. These can be set at the API, or API method level.
What are usage plans and API keys?
A usage plan specifies who can access one or more deployed API stages and methods—and optionally sets the target request rate to start throttling requests. The plan uses API keys to identify API clients and who can access the associated API stages for each key.
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 Lambda authorizers, IAM roles, or Amazon Cognito 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.
An API key has a name and a value. (The terms "API key" and "API key value" are often
used interchangeably.) The name cannot exceed 1024 characters. The value is an alphanumeric string between 20 and 128
characters, for example, apikey1234abcdefghij0123456789.
Important
API key values must be unique. 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.
An API key can be associated with more than one usage plan. A usage plan can be associated with more than one stage. However, a given API key can only be associated with one usage plan for each stage of your API.
A throttling limit sets the target point at which request throttling should start. This can be set at the API or API method level.
A quota limit sets the target maximum number of requests with a given API key that can be submitted within a specified time interval. You can configure individual API methods to require API key authorization based on usage plan configuration.
Throttling and quota limits apply to requests for individual API keys that are aggregated across all API stages within a usage plan.
Note
Usage plan throttling and quotas are not hard limits, and are applied on a best-effort basis. In some cases, clients can exceed the quotas that you set. Don’t rely on usage plan quotas or throttling to control costs or block access to an API. Consider using AWS Budgets to monitor costs and AWS WAF to manage API requests.
Steps to configure a usage plan and API keys in API Gateway
The following tasks outline the required steps to configure a usage plan and API keys. For best practices, see Best practices for API keys and usage plans.
To configure a usage plan and API keys
-
Create an API and configure the method request for each API method to require an API key. Then, deploy your API to a stage.
To include API methods in a usage plan, you must configure individual API methods to require an API key.
For more information about how to configure a method to require an API key, see Require an API key on a method.
-
Generate or import API keys to distribute to application developers (your customers) who will be using your API. API keys are required for your usage plan.
For more information about how to generate or import API keys, see Create an API key.
-
Create the usage plan with the desired throttle and quota limits, and then associate API stages and API keys with the usage plan.
For more information about how to create the usage plan, see Create a usage plan.
Callers of the API must supply an assigned API key in the x-api-key
header in requests to the API.
For a complete AWS CloudFormation template that creates and associates a usage plan with a new stage and an API key, see Create and configure API keys and usage plans with AWS CloudFormation.
Best practices for API keys and usage plans
The following are suggested best practices to follow when using API keys and usage plans.
Important
-
Don't use API keys for authentication or authorization to control access to your APIs. If you have multiple APIs in a usage plan, a user with a valid API key for one API in that usage plan can access all APIs in that usage plan. Instead, to control access to your API, use an IAM role, a Lambda authorizer, or an Amazon Cognito user pool.
-
Use API keys that API Gateway generates. API keys shouldn't include confidential information; clients typically transmit them in headers that can be logged.
-
If you're using a developer portal to publish your APIs, note that all your APIs in a given usage plan can be subscribed to by customers, even if you haven't made them visible to your customers.
-
In some cases, clients can exceed the quotas that you set. Don’t rely on usage plans to control costs. Consider using AWS Budgets to monitor costs and AWS WAF to manage API requests.
-
After you add an API key to a usage plan, the update operation might take a few minutes to complete.
