This chapter covers API Gateway API keys and usage plans, a core mechanism for controlling access and throttling API usage in AWS. For the DVA-C02 exam, this topic falls under Domain 2: Security (Objective 2.4: Implement a secure API Gateway). Expect 2-3 questions directly testing your knowledge of how API keys, usage plans, and API stages interact, including common misconfigurations and quota behaviors. Mastering this topic is essential for designing secure, cost-controlled serverless APIs.
Jump to a section
Think of an API Gateway deployment as a subway system. The API itself is the entire subway network with many lines and stations (endpoints). An API key is like a reusable subway token or a transit card. Each token has a unique serial number (the API key value) that the turnstile (API Gateway) reads before granting access. A usage plan is like a fare zone or a ticket package: it defines how many rides (requests) are allowed per day, week, or month. If you buy a monthly pass (a usage plan with a 10,000 request limit), the turnstile tracks your rides and when you hit 10,000, the turnstile locks you out until the next month. The subway operator (you, the developer) can issue different types of tokens: some tokens are for single rides (API keys for testing), some are for unlimited rides (keys without a usage plan), and some are tied to specific plans. The turnstile does not care who holds the token—it just checks the token's serial number against its database of active plans and remaining quota. If you try to use a token that has expired or exceeded its quota, the turnstile rejects you with a 403 Forbidden. In AWS, the API Gateway acts as the turnstile, the API key is the token, and the usage plan is the fare zone that enforces rate limits and quotas.
What Are API Gateway API Keys and Usage Plans?
API Gateway API keys are alphanumeric strings that you can use to identify and control access to your APIs. They are not a security mechanism by themselves—they are primarily for usage tracking and throttling. Usage plans define a set of throttling and quota rules that can be applied to API keys. Together, they allow you to manage how many requests a client can make and at what rate.
Why Do They Exist?
In a serverless architecture, you often expose APIs to multiple clients—mobile apps, web apps, third-party partners. Without controls, a single misbehaving client could overwhelm your backend. API keys and usage plans let you enforce request rate limits and daily/weekly/monthly quotas per client. They also enable you to monetize your API by offering different tiers (e.g., free tier: 1000 requests/day, paid tier: 100,000 requests/day).
How API Keys Work Internally
An API key is a 40-character string (e.g., abc123...). When a client sends a request to an API Gateway endpoint, they include the API key in the x-api-key header (or as a query string parameter if configured). API Gateway then:
1. Extracts the API key from the request.
2. Looks up the key in its database (stored within the API Gateway service).
3. Checks if the key is associated with a usage plan.
4. If yes, checks the current usage against the plan's throttle and quota limits.
5. If limits are not exceeded, forwards the request to the backend (e.g., Lambda, HTTP, mock).
6. If limits are exceeded, returns a 429 Too Many Requests (for throttle) or 403 Forbidden (for quota exceeded) response.
Key Components and Defaults
- API Key Source: By default, API Gateway expects the API key in the x-api-key header. You can also configure it to use a query string parameter named api-key or apikey.
- Usage Plan: Contains throttle settings (rate and burst) and quota settings (limit and period).
- Throttle: rate (requests per second) and burst (maximum requests in a burst). Default: 10,000 rps for regional APIs, but you can set lower.
- Quota: limit (number of requests) and period (DAY, WEEK, or MONTH). Default: no quota.
- API Stage: You associate an API key with a specific stage (e.g., prod, dev). The same key can be used across multiple stages.
- Key Type: Can be AUTO (API Gateway generates a 40-character key) or IMPORT (you provide your own key value).
Configuration Steps
To configure API keys and usage plans, you typically use the AWS Management Console, AWS CLI, or SDK. Here’s the CLI workflow:
Create a usage plan:
aws apigateway create-usage-plan \
--name "FreeTier" \
--description "Free tier: 1000 requests per day" \
--quota limit=1000,period=DAY \
--throttle rate=10,burst=20Create an API key:
aws apigateway create-api-key \
--name "Client1Key" \
--description "Key for client 1" \
--enabled \
--generate-distinct-idAssociate the key with a usage plan:
aws apigateway create-usage-plan-key \
--usage-plan-id <usage-plan-id> \
--key-type API_KEY \
--key-id <api-key-id>Associate the usage plan with an API stage:
aws apigateway update-usage-plan \
--usage-plan-id <usage-plan-id> \
--add-op path=/apiStages,value="<api-id>:<stage>"Enable API key requirement on methods:
In the API Gateway console, for each method, set "API Key Required" to true.
Via CLI: update the method's apiKeyRequired property.
How It Interacts with Related Technologies
Lambda Authorizers: API keys can be used alongside Lambda authorizers. The authorizer can validate the key and also check additional claims. However, if you use a usage plan, the key must be present in the request.
Cognito User Pools: You can use Cognito to issue API keys to users, but that is not typical. Usually, Cognito tokens are used with authorizers, while API keys are for third-party clients.
WAF: AWS WAF can also rate-limit requests, but WAF operates at the HTTP level and can block IPs, while usage plans are per-key.
CloudWatch Metrics: API Gateway emits metrics like Count and 4XXError that include usage plan information. You can set alarms on Throttle or QuotaExceeded metrics.
Common Trap Patterns
Trap 1: Thinking API keys provide security. They do not—anyone who can read the key (e.g., from a mobile app binary) can use it. API keys should be treated as identifiers, not secrets. For security, use IAM roles or Cognito.
Trap 2: Confusing throttle and quota. Throttle is rate-based (requests per second), quota is limit-based (total requests over a period). A request can be throttled even if quota is not exceeded, and vice versa.
Trap 3: Assuming API keys are automatically associated with a usage plan. You must explicitly associate the key with a plan and the plan with a stage.
Trap 4: Forgetting to enable "API Key Required" on the method. Without this, API Gateway ignores the key even if present.
Trap 5: Using the same API key across multiple usage plans—a key can only belong to one usage plan at a time.
Specific Values and Exam Numbers
API key length: 40 characters (alphanumeric).
Default throttle for regional APIs: 10,000 rps (can be increased via service limit increase).
Quota periods: DAY (24-hour window), WEEK (Monday–Sunday), MONTH (calendar month).
Burst limit: Maximum requests in a short burst (e.g., 5000). If burst is exceeded, a 429 is returned.
API Gateway returns 429 Too Many Requests for throttle violations and 403 Forbidden for quota violations (or 429 if you have configured custom responses).
The x-api-key header is case-insensitive.
Verification Commands
To test if an API key is working:
curl -X GET https://<api-id>.execute-api.<region>.amazonaws.com/<stage>/resource \
-H "x-api-key: <api-key-value>"To check usage:
aws apigateway get-usage \
--usage-plan-id <plan-id> \
--key-id <key-id> \
--start-date "2025-01-01" \
--end-date "2025-01-31"This returns a list of usage records per day.
Edge Cases
Key Deletion: If you delete an API key, any in-flight requests using that key will fail with 403.
Stage Association: A usage plan can be associated with multiple stages (e.g., dev and prod), but the quota is shared across all stages. If you want separate quotas, create separate plans.
API Key Regeneration: You can regenerate a key (change its value) without deleting it. Existing clients must update their key.
Usage Plan Limits: You can have up to 10,000 API keys per region per account (soft limit).
Create a Usage Plan
First, define the throttling and quota rules. In the AWS Console, go to API Gateway > Usage Plans > Create. Set a name, description, throttle rate (e.g., 10 requests per second) and burst (e.g., 20). Set quota limit (e.g., 1000) and period (DAY). Click Create. This plan will later be associated with an API stage. The plan itself does nothing until associated.
Create an API Key
Next, create one or more API keys. In the Console, go to API Gateway > API Keys > Create. Provide a name, optional description, and choose key type: AUTO (generated) or IMPORT (your own value). Set Enabled to True. Click Save. The key value is shown once; copy and store it securely. You can also generate keys via CLI using `create-api-key`.
Associate API Key with Usage Plan
Now link the key to the plan. In the Console, open the usage plan, go to the Associated API Keys tab, click Add API Key, select the key, and confirm. This associates the key with the plan's rules. A key can belong to only one usage plan at a time. If you need different limits, create multiple keys or multiple plans.
Associate Usage Plan with API Stage
The usage plan must be associated with a specific API stage (e.g., prod). In the usage plan, go to Associated Stages, click Add Stage, select the API and stage. Now the plan's rules apply to that stage. You can associate the same plan with multiple stages, but the quota is shared across them.
Enable API Key Requirement on Methods
For each API method (GET, POST, etc.) that should require an API key, set API Key Required to true. In the Console, select the method, go to Method Request, and toggle API Key Required. If this is not enabled, API Gateway will ignore the key even if present. After enabling, any request without a valid key will receive a 403 Forbidden.
Enterprise Scenario 1: SaaS API with Tiered Pricing
A company offers a weather data API with three tiers: Free (100 requests/day), Pro (10,000 requests/day), and Enterprise (unlimited). They create three usage plans: free-tier, pro-tier, enterprise-tier. Each customer gets a unique API key (AUTO generated). The key is associated with the appropriate plan. The API is deployed to a production stage. The company uses CloudWatch metrics to track usage per key and sends alerts when customers approach their quota. Misconfiguration: If the developer forgets to enable API Key Required on the method, any client can call the API without a key, bypassing throttling. The fix: enable the flag on all methods.
Enterprise Scenario 2: Internal Microservices with Rate Limiting
A large e-commerce platform exposes internal APIs for order processing. Each microservice team gets an API key with a usage plan that limits calls to 1000 requests per second (rate) with a burst of 2000. This prevents one team's bug from overwhelming the backend. The usage plans are associated with the prod stage. The operations team uses get-usage CLI to audit daily usage. A common issue: a team accidentally shares their API key in a public repository. The key is compromised and used by an attacker. The solution: regenerate the key and update the client. Also, use IAM authorization for internal APIs instead of API keys for better security.
Enterprise Scenario 3: Mobile App Backend with User-Specific Quotas
A social media app uses API Gateway with Lambda. Each user is assigned a unique API key tied to a usage plan that allows 500 requests per day. The mobile app retrieves the key from a secure backend on login. However, the app stores the key locally, so if a user reverse-engineers the app, they can extract the key and share it. The key is then used by many users, exhausting the quota quickly. The company mitigates this by using Cognito User Pools with a Lambda authorizer instead of API keys, or by implementing per-user quotas using a custom usage plan per user (not scalable). Better approach: use Cognito identity pools to get temporary AWS credentials and use IAM authorization.
Performance and Scale Considerations
API Gateway can handle millions of API keys and usage plans. However, each request incurs a lookup overhead. For very high throughput, consider using a regional API endpoint (not edge-optimized) to reduce latency. Also, if you need to invalidate a key quickly, deletion is immediate. The default throttle limit for an API is 10,000 rps; you can request a limit increase. For quotas, the reset time is based on the period: DAY resets at midnight UTC, WEEK resets on Monday 00:00 UTC, MONTH resets on the first day of the month at 00:00 UTC.
DVA-C02 Exam Focus: API Keys and Usage Plans
This topic is tested under Domain 2: Security (Objective 2.4). Expect 2-3 questions. The exam will test your understanding of the mechanism, not just definitions.
Common Wrong Answers and Why
"API keys provide authentication." Wrong. API keys are for identification and usage tracking, not authentication. They do not verify the identity of the caller. Candidates choose this because they think of keys as passwords. The correct answer: API keys are for throttling and quotas; use IAM or Cognito for authentication.
"API keys are automatically required when you create a usage plan." Wrong. You must explicitly enable API Key Required on each method. Candidates think the plan itself enforces the key requirement. The correct answer: the method must be configured to require a key.
"Quota exceeded returns 429." Wrong. Quota exceeded returns 403 Forbidden. Throttle exceeded returns 429. Candidates confuse the two. The correct answer: 403 for quota, 429 for throttle.
"A usage plan can be associated with multiple API keys." True, but the common trap is thinking a key can be in multiple plans. It cannot. Candidates often answer that a key can be in multiple plans. The correct answer: a key belongs to one plan.
"API keys are stored in DynamoDB." Wrong. API keys are stored internally in API Gateway, not in DynamoDB. Candidates guess DynamoDB because it's a common AWS database.
Specific Numbers and Terms on the Exam
API key length: 40 characters.
Header name: x-api-key.
Quota periods: DAY, WEEK, MONTH.
Throttle vs. quota: rate (per second) vs. limit (total).
Default throttle: 10,000 rps for regional APIs.
Response codes: 429 (throttle), 403 (quota).
CLI commands: create-usage-plan, create-api-key, create-usage-plan-key, get-usage.
Edge Cases Tested
Same API key across stages: If a usage plan is associated with multiple stages, the quota is shared. A request to stage A counts against the same quota as a request to stage B. This can cause unexpected throttling.
API key regeneration: After regenerating, the old key stops working immediately. Clients must use the new key.
API key disabled: If a key is disabled, requests with that key get 403 Forbidden.
Multiple usage plans for one API: You can have multiple usage plans associated with the same stage, each with different keys. This allows tiered access.
How to Eliminate Wrong Answers
If the question mentions "authentication" or "identity", eliminate API keys as the sole answer. Look for IAM, Cognito, or Lambda authorizer.
If the question says "rate limiting per second", it's throttle. If "total requests per day", it's quota.
If the question asks how to enforce API key usage, the answer must include enabling "API Key Required" on the method.
If the question involves a key that stops working, check if it was deleted, disabled, or regenerated.
Remember: API keys are not secure—they can be shared or stolen. For secure APIs, use IAM roles or Cognito.
API keys are 40-character identifiers used for usage tracking and throttling, not security.
Usage plans define throttle (rate per second) and quota (total requests per day/week/month).
Throttle exceeded returns 429; quota exceeded returns 403.
You must enable 'API Key Required' on each method for keys to be enforced.
A usage plan must be associated with an API stage to take effect.
An API key can belong to only one usage plan at a time.
API keys are stored internally in API Gateway, not in DynamoDB.
These come up on the exam all the time. Here's how to tell them apart.
API Keys with Usage Plans
Provides throttling and quota enforcement per key.
API key is a static string, easy to implement.
No authentication; anyone with the key can use it.
Suitable for third-party API access with tiered pricing.
Key management is manual (create, delete, regenerate).
Lambda Authorizers
Provides authentication and authorization via custom logic.
Can validate tokens from Cognito, JWT, or other sources.
Supports fine-grained access control based on claims.
Suitable for user-specific access with secure authentication.
Requires Lambda function, more complex to implement.
Mistake
API keys are a form of authentication.
Correct
API keys are for identification and usage tracking, not authentication. They do not verify the caller's identity. Use IAM roles, Cognito, or Lambda authorizers for authentication.
Mistake
Once a usage plan is created, all API methods automatically require an API key.
Correct
You must explicitly set 'API Key Required' to true on each method. Without this, API Gateway does not check for a key.
Mistake
A single API key can be associated with multiple usage plans.
Correct
An API key can belong to only one usage plan at a time. If you need different limits, create separate keys.
Mistake
Quota exceeded returns HTTP 429 Too Many Requests.
Correct
Quota exceeded returns 403 Forbidden. Throttle exceeded returns 429. The exam tests this distinction.
Mistake
API keys are stored in DynamoDB or another AWS service.
Correct
API keys are stored internally within API Gateway. They are not accessible via DynamoDB or any other service.
Reveal each answer, then mark whether you got it right. Score 60%+ to unlock the next chapter.
In the API Gateway console, select the method, go to Method Request, and set 'API Key Required' to true. Alternatively, use the CLI: `aws apigateway update-method --rest-api-id <id> --resource-id <id> --http-method GET --patch-operations op=replace,path=/apiKeyRequired,value=true`. Without this, API Gateway will not check for an API key.
Throttle limits the rate of requests per second (e.g., 10 requests per second) and includes a burst limit. Quota limits the total number of requests over a day, week, or month (e.g., 1000 requests per day). Throttle returns 429 when exceeded; quota returns 403. Both can be set independently.
Yes, you can associate a usage plan with multiple stages (e.g., dev and prod). The key works on all stages, but the quota is shared across them. If you want separate quotas, create separate usage plans for each stage.
Use the AWS CLI: `aws apigateway update-api-key --api-key <key-id> --patch-operations op=replace,path=/value,value=<new-key-value>`. The new key takes effect immediately. Old clients will be rejected unless they use the new key.
Requests using that key will receive a 403 Forbidden response. To re-enable, set the key's enabled status to true. Disabling is immediate and does not affect other keys.
Yes, API keys work with custom domain names. The client must include the `x-api-key` header in requests to the custom domain. The key is validated against the usage plan associated with the stage.
Use CloudWatch metrics (Count, 4XXError) or the `get-usage` CLI command to retrieve usage records per key. You can also set CloudWatch alarms on the `Throttle` or `QuotaExceeded` metrics.
You've just covered API Gateway API Keys and Usage Plans — now see how well it sticks with free DVA-C02 practice questions. Full explanations included, no account needed.
Done with this chapter?