Usage plans & API keys

An API key identifies a caller, such as one customer's app. A usage plan lists the API stages its keys can call, with the throttle and quota each key gets. Both work with REST and WebSocket APIs.

API keys identify callers but don't authenticate them: pair them with an authorizer for that. A REST method checks keys only when its API key required switch is on, as the Authorizers and resource policies guide describes; on a WebSocket API the key is checked when a client connects.

Callers send the key in the x-api-key header. A REST API can instead take it from a custom authorizer, when its API key source is AUTHORIZER. Pods rejects a call with 403 Forbidden when the key is missing, unknown or disabled, or isn't in a plan that covers the stage. A caller over its throttle gets 429 Too Many Requests, and one over its quota gets 429 Limit Exceeded.

Changes to keys and plans reach the gateway without a redeploy, usually within a minute.

To create a usage plan, choose Usage → Usage Plans in the Pods sidebar, then New Usage Plan. Owners, Admins and Managers can manage plans.

1. Type a Name, up to 128 characters. It's required.
2. Optional: write a Description, up to 1,024 characters.
3. Optional: set a throttle, Rate (requests/sec) and Burst. Leave both empty for no plan throttle.
4. Optional: set a quota, Limit (requests), Period (Day, Week or Month) and Offset. Leave the limit empty for no quota.
5. Choose Create Usage Plan.

The plan opens on its edit page, where you add API stages and keys. Its limits can't exceed the project's throttle, which is 10,000 requests a second with a burst of 5,000 unless it's changed under Settings → General.

Choose Usage → Usage Plans in the sidebar to see every plan in the project. The figures across the top count Total plans and how many are Throttled, have a quota (With quota) or have No limits.

Narrow the list with the Limits filter, or search by name, description or plan ID. Each row shows the plan's Throttle, Quota, Plan ID and when it was last Updated. The list shows 25 plans a page; switch to 10, 50 or 100 at the bottom.

Click a plan to open it. Each row's ⋯ menu has Edit (or Open for Members), Copy plan ID and Delete.

A usage plan's Settings section holds its Name, Description, Throttle and Quota. Change them, then choose Save Changes at the top. Gateways pick the change up without a redeploy.

• Throttle: the steady rate and the burst each key in the plan gets. Leave both empty for no plan throttle.
• Quota: how many requests each key can make per period. Day periods start at 00:00 UTC, Week periods on Sunday at 00:00 UTC, and Month periods on the 1st. The Offset is taken off the limit in the first period.

To delete a plan, choose Delete Usage Plan under Danger zone, or Delete in the plan's ⋯ menu in the list, and confirm. Its keys lose access to the plan's stages, and it can't be undone.

A usage plan covers the API stages listed in its Stages section. Keys in the plan can call those stages. To add one, open the plan, choose Stages, then Add Stage. Pick the API (REST and WebSocket APIs only) and the Stage, and confirm.

To give single methods their own limits, choose Method throttles in the stage's ⋯ menu. Enter JSON whose keys are /path/METHOD, such as {"/pets/GET": {"rateLimit": 10, "burstLimit": 20}}, up to 20 entries. They replace the plan throttle for the methods listed, and can't exceed the project throttle.

Remove in the stage's ⋯ menu takes the stage out of the plan after you confirm.

To let a key use a plan, open the plan, choose API Keys, then Add API Key. Pick the API key and confirm.

A key can be in up to 10 plans, but not in two plans that cover the same API stage. Each key in the list shows the last characters of its value and whether it's Enabled or Disabled. Its ⋯ menu has Copy key ID and Remove from plan, which asks you to confirm.

A plan's Usage section shows how many requests each of its keys made per day, and how much quota was left. Pick a Start and End date (the last seven days to begin with, up to 366 days), then choose Load Usage. Today's numbers are live; earlier days come from daily totals. Export CSV downloads the report.

When the plan has a quota, Adjust Quota changes one key's allowance for the current period only:

• Extend: adds requests to this period.
• Set: sets the requests remaining this period.
• Reset: goes back to the plan's quota.

Pick the API key and the Operation, type the number of Requests for Extend or Set, and confirm. The next period starts from the plan's quota again.

To create an API key, choose Usage → API Keys in the sidebar, then New API Key. Owners, Admins and Managers can manage keys.

1. Type a Name, up to 128 characters. It's required.
2. Optional: in Custom value, type the key yourself: 20 to 128 letters, digits, dashes or underscores. Leave it empty and Pods generates 40 random characters.
3. Optional: add a Description and a Customer ID, your own identifier for whoever holds the key.
4. Choose Create API Key.

Pods shows the key's value once. Copy it then: it's never stored in readable form, and only Owners and Admins can reveal it later. Then add the key to a usage plan so it can call an API stage.

The API Keys list counts Total keys, Enabled and Disabled. Filter by Status, or search by name, customer or the end of the value. Each row shows the last characters of the value, the customer, the status and when the key was Last used. Each key's ⋯ menu has:

• Edit (or Open): the key's page, with its Name, Description, Customer ID, an Enabled switch and the usage plans it's in. Choose Save Changes after editing.
• Reveal value: shows the full value. Owners and Admins only, and each reveal is recorded in the audit log.
• Copy key ID.
• Rotate: creates a new key with a new value, shown once, in the same usage plans. The old key stays enabled until you disable it.
• Disable or Enable: Pods asks before disabling. Callers using a disabled key are rejected within a minute.
• Delete: after you confirm, callers using the key are rejected and it leaves every usage plan. It can't be undone.

To bring in keys you already use, choose Import CSV on the API Keys screen and paste a CSV with the header Name,Key,Description,Enabled,UsagePlanIds, the format AWS API Gateway exports.

Choose Import to skip rows with problems and list them as warnings, or Import (Fail on Warnings) to import nothing if any row has a problem. An Enabled value that isn't true or false is treated as true, with a warning. Owners, Admins and Managers can import keys.