Before configuring a usage plan, you must have already done the following: set up
methods of a selected API to require API keys, deployed or redeployed the API to a
stage, and created or imported one or more API keys. For more information, see Set Up API Keys Using the API Gateway
REST API.

To configure a usage plan by using the API Gateway REST API, use the following instructions,
assuming that you've already created the APIs to be added to the usage
plan.

Create a Usage
Plan

Call usageplan:create to create a usage plan. In the payload,
specify the name and description of the plan, associated API stages, rate
limits, and quotas.

Make note of the resultant usage plan identifier. You need it in the next
step.

Do one of the following:

Call usageplankey:create to add an API key to the usage
plan. Specify keyId and keyType in the
payload.

To add more API keys to the usage plan, repeat the previous call,
one API key at a time.

Call apikey:import to add one or more API keys directly to
the specified usage plan. The request payload should contain API key
values, the associated usage plan identifier, the Boolean flags to
indicate that the keys are enabled for the usage plan, and,
possibly, the API key names and descriptions.

The following example of the apikey:import request
adds three API keys (as identified by key,
name, and description) to one usage
plan (as identified by usageplanIds):

As a result, three UsagePlanKey resources are created
and added to the UsagePlan.

You can also add API keys to more than one usage plan this way. To
do this, change each usageplanIds column value to a
comma-separated string that contains the selected usage plan
identifiers, and is enclosed within a pair of quotes
("n371pt,m282qs" or
'n371pt,m282qs').

Call usage:update to grant an extension to the current usage in a
usage plan.

Test Usage Plans

As an example, let's use the PetStore API, which was created in Build an API Gateway API from an Example. Assume that the API is
configured to use an API key of Hiorr45VR...c4GJc. The following steps
describe how to test a usage plan.

To test your usage plan

Make a GET request on the Pets resource (/pets),
with the ?type=...&page=... query parameters, of the API
(for example, xbvxlpijch) in a usage plan:

You must submit this request to the execute-api component
of API Gateway and provide the required API key (for example,
Hiorr45VR...c4GJc) in the required
x-api-key header.

The successful response returns a 200 OK status code and a
payload that contains the requested results from the backend. If you forget
to set the x-api-key header or set it with an incorrect key,
you get a 403 Forbidden response. However, if you didn't
configure the method to require an API key, you will likely get a 200
OK response whether you set the x-api-key header
correctly or not, and the throttle and quota limits of the usage plan are
bypassed.

Occasionally, when an internal error occurs where API Gateway is unable to
enforce usage plan throttling limits or quotas for the request, API Gateway serves
the request without applying the throttling limits or quotas as specified in
the usage plan. But, it logs an error message of Usage Plan check
failed due to an internal error in
your
CloudWatch logs. You can ignore such occasional errors.

Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's
Help pages for instructions.