API Gateway usage plans and API keys
API Gateway usage plans and API keys are a metering and rate-limiting mechanism. They are not an access-control mechanism, and AWS is explicit about that: “Don’t use API keys for authentication or authorization to control access to your APIs.”
What an API key actually is
Section titled “What an API key actually is”An API key is an alphanumeric string that identifies a calling application so API Gateway can attribute requests to it. A usage plan associates one or more API keys with one or more deployed API stages and applies a throttling rate and a quota to each key.
That is the whole of it. A key is not a credential in any meaningful sense:
- A key is not scoped to an API. If several APIs sit in the same usage plan, a caller holding a valid key for one of them can call all of them.
- A key is not a secret. Clients transmit keys in request headers, which are routinely written to access logs, proxy logs and browser developer tools. AWS advises that API keys should not contain confidential information for exactly this reason.
- A key carries no identity. There is no subject, no expiry, no signature and nothing to verify. Anyone in possession of the string is indistinguishable from the intended caller.
Use a real authoriser for access control
Section titled “Use a real authoriser for access control”To control who may call an API, choose one of the mechanisms API Gateway provides for that purpose:
| Mechanism | Use it when |
|---|---|
| IAM authorisation (SigV4) | Callers are AWS principals — other services, roles, or workloads inside your accounts. |
| Lambda authoriser | You need to validate a bearer token or apply authorisation logic API Gateway does not model natively. |
| Amazon Cognito user pool authoriser | End users sign in to a Cognito user pool and the API accepts the resulting JWT. |
| Mutual TLS | Machine-to-machine callers present a client certificate you issue. |
A usage plan then layers on top of whichever of these you chose, so each identified client gets its own rate and quota. The authoriser decides whether the call is allowed; the usage plan decides how often.
Usage-plan limits are best effort
Section titled “Usage-plan limits are best effort”Throttling rates and quotas in a usage plan are applied on a best-effort basis. AWS states plainly that clients can exceed the quotas you set, and that you should not rely on usage plans to control cost or to block access. Treat them as a smoothing mechanism, not a control.
Where the requirement is a hard boundary rather than a soft one:
- Use AWS WAF in front of the API to block or rate-limit request patterns.
- Use AWS Budgets and budget actions to catch runaway spend.
- Enforce per-tenant limits in the application, where you can reason about them transactionally.
Practical shape of a secured API
Section titled “Practical shape of a secured API”- Attach an authoriser (IAM, Lambda or Cognito) to every method that is not deliberately public.
- Issue an API key per client and put it in a usage plan sized for that client’s contract.
- Turn on access logging and CloudWatch metrics per stage so a key that misbehaves is visible.
- Rotate a key by issuing a new one, moving the client across, and deleting the old key — which is possible precisely because the key is an identifier, not a credential.
- Put AWS WAF in front of the stage for anything internet-facing.