API keys and usage plans in AWS - Deep Dive

Overview - API keys and usage plans

What is it?

API keys are unique codes given to users or applications to identify and control their access to an API. Usage plans define how much and how often these users can call the API, setting limits like the number of requests per second or total requests per day. Together, they help manage who uses the API and how much they can use it. This keeps the API safe and reliable for everyone.

Why it matters

Without API keys and usage plans, anyone could use an API without limits, causing slowdowns or crashes. This would be like a store with no entry control, where too many people crowd in and break things. By controlling access and usage, businesses protect their services, ensure fair use, and can even charge users based on their consumption.

Where it fits

Before learning about API keys and usage plans, you should understand what APIs are and how they work. After this, you can learn about advanced API security, monitoring, and billing strategies. This topic fits in the journey of managing and securing cloud services.

Mental Model

Core Idea

API keys identify users, and usage plans set rules on how much they can use the API to keep it safe and fair.

Think of it like...

Think of an API key like a membership card to a gym, and the usage plan like the gym's rules on how many times you can visit each week and what equipment you can use.

┌───────────────┐      ┌───────────────┐
│   API User    │─────▶│   API Key     │
└───────────────┘      └───────────────┘
                            │
                            ▼
                    ┌─────────────────┐
                    │ Usage Plan Rules│
                    │ - Rate Limits   │
                    │ - Quotas        │
                    └─────────────────┘
                            │
                            ▼
                    ┌─────────────────┐
                    │   API Gateway   │
                    └─────────────────┘

Build-Up - 7 Steps

1

Foundation

What is an API key

Concept: API keys are simple codes that identify who is calling an API.

An API key is like a password or ID card for an application or user. When you call an API, you include this key so the API knows who you are. It helps the API decide if you are allowed to use it.

Result

You can recognize and track each user or app calling your API.

Understanding that API keys are identifiers helps you see how APIs control access and monitor usage.

2

Foundation

What is a usage plan

Concept: Usage plans set limits on how much an API key can use the API.

A usage plan defines rules like how many requests a user can make per second or per day. It prevents any one user from overloading the API. For example, a plan might allow 1000 requests per day and 10 requests per second.

Result

API usage is controlled and balanced among users.

Knowing usage plans protect the API from overload helps you design fair and stable services.

3

Intermediate

How API keys and usage plans work together

🤔Before reading on: do you think API keys alone can limit usage, or do usage plans add something extra? Commit to your answer.

Concept: API keys identify users, but usage plans enforce limits on their API calls.

When a user calls an API, the API key tells the system who they are. The usage plan linked to that key then checks if the user is within their allowed limits. If they exceed the limits, the API blocks or slows down their requests.

Result

Users are identified and their usage is controlled in real time.

Understanding the separation of identification (API key) and control (usage plan) clarifies how APIs manage access and protect resources.

4

Intermediate

Setting rate limits and quotas

🤔Before reading on: do you think rate limits and quotas are the same, or do they serve different purposes? Commit to your answer.

Concept: Rate limits control how fast requests happen; quotas control total usage over time.

Rate limits restrict how many requests can be made per second or minute to prevent bursts. Quotas limit the total number of requests over a longer period, like a day or month. Both work together to keep the API stable and fair.

Result

API usage is smooth and predictable, avoiding sudden spikes or overuse.

Knowing the difference between rate limits and quotas helps you design balanced usage plans that protect APIs effectively.

5

Intermediate

Assigning usage plans to API keys

Concept: Each API key is linked to one or more usage plans to define its limits.

In AWS API Gateway, you create usage plans with specific limits. Then you attach API keys to these plans. This way, each user or app has a clear set of rules they must follow when calling the API.

Result

Users have personalized limits based on their assigned usage plans.

Understanding this linkage allows flexible control over different user groups or customers.

6

Advanced

Monitoring and throttling in usage plans

🤔Before reading on: do you think throttling stops requests immediately or queues them? Commit to your answer.

Concept: Usage plans monitor usage and throttle requests that exceed limits to protect the API.

When a user exceeds rate limits, the API Gateway throttles requests by rejecting or delaying them. Monitoring tools track usage and alert administrators if limits are approached or breached. This helps maintain API health and user fairness.

Result

API remains responsive and stable even under heavy or abusive use.

Knowing how throttling works helps you anticipate user experience and design better APIs.

7

Expert

Advanced usage plan strategies and surprises

🤔Before reading on: do you think usage plans can share limits across multiple APIs or keys? Commit to your answer.

Concept: Usage plans can be shared across multiple APIs and keys, and have nuances in enforcement that affect real-world use.

In AWS, a usage plan can include multiple APIs and stages, allowing shared limits across different services. Also, usage plans enforce limits per API key, but if keys are shared or leaked, limits can be bypassed. Additionally, usage plans do not encrypt API keys, so secure storage is essential. Understanding these details helps avoid common pitfalls.

Result

You can design complex, multi-API usage controls and avoid security risks.

Knowing these advanced behaviors prevents misuse and helps build scalable, secure API ecosystems.

Under the Hood

When an API call arrives, the API Gateway extracts the API key from the request. It looks up the usage plan linked to that key and checks the current usage counters against the plan's limits. If the call is within limits, it forwards the request to the backend service. If not, it rejects or throttles the request. Usage data is updated in real time to track consumption.

Why designed this way?

This design separates identification (API key) from control (usage plan) to allow flexible management. It supports multiple users with different limits and enables monitoring and billing. Alternatives like IP-based limits are less precise. This approach balances security, scalability, and usability.

┌───────────────┐
│ Incoming Call │
└──────┬────────┘
       │ Extract API Key
       ▼
┌───────────────┐
│ Lookup Usage  │
│ Plan & Limits │
└──────┬────────┘
       │ Check Limits
       ▼
┌───────────────┐      ┌───────────────┐
│ Within Limits │─────▶│ Forward to    │
│               │      │ Backend API   │
└───────────────┘      └───────────────┘
       │
       ▼
┌───────────────┐
│ Exceeded Limit│
│ Throttle/Reject│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think API keys alone stop users from overusing an API? Commit to yes or no.

Common Belief: API keys by themselves prevent users from making too many requests.

Reality: API keys only identify users; usage plans enforce limits to control usage.

Why it matters: Relying on API keys alone can lead to unlimited usage, causing API overload and downtime.

Quick: Do you think usage plans can protect an API if the API key is leaked? Commit to yes or no.

Common Belief: Usage plans fully protect the API even if the API key is shared or stolen.

Reality: If an API key is leaked, anyone with it can use the API within the usage plan limits, potentially abusing the service.

Why it matters: Ignoring key security risks can lead to unauthorized usage and unexpected costs.

Quick: Do you think rate limits and quotas are the same thing? Commit to yes or no.

Common Belief: Rate limits and quotas are interchangeable terms for limiting API usage.

Reality: Rate limits control how fast requests happen; quotas limit total requests over time.

Why it matters: Confusing these can cause poor API performance or unfair user restrictions.

Quick: Do you think usage plans automatically encrypt API keys? Commit to yes or no.

Common Belief: API Gateway usage plans encrypt API keys to keep them safe.

Reality: API keys are not encrypted by usage plans; secure storage and transmission are the user's responsibility.

Why it matters: Assuming encryption leads to careless key handling and security breaches.

Expert Zone

1

Usage plans can include multiple APIs and stages, allowing shared limits across different services, which is useful for complex API ecosystems.

2

API keys are simple strings without built-in encryption or expiration, so managing their lifecycle and rotation is critical for security.

3

Throttling behavior can cause user requests to be rejected abruptly, impacting user experience; designing graceful degradation strategies is important.

When NOT to use

Usage plans and API keys are not suitable for highly sensitive APIs requiring strong authentication and authorization; in such cases, use OAuth tokens, JWTs, or AWS IAM roles instead.

Production Patterns

In production, usage plans are used to create tiers of API access (free, standard, premium) with different limits and pricing. API keys are distributed to customers or apps, and usage is monitored for billing and abuse detection.

Connections

OAuth 2.0

OAuth provides a more secure and flexible authorization method compared to API keys and usage plans.

Understanding API keys and usage plans helps grasp the basics before moving to OAuth, which adds user consent and token scopes.

Rate Limiting in Networking

Usage plans implement rate limiting, a concept also used in network traffic control to prevent congestion.

Knowing how rate limiting works in APIs connects to broader principles of managing shared resources fairly.

Library Book Lending Systems

Usage plans are like borrowing limits in libraries, controlling how many books a member can borrow and for how long.

This cross-domain link shows how controlling access and usage is a common problem in many systems.

Common Pitfalls

#1 Using the same API key for multiple users to avoid creating many keys.

Wrong approach:

Sharing one API key among all users to simplify management.

Correct approach:

Create unique API keys for each user or application to track and control usage individually.

Root cause:

Misunderstanding that API keys identify users and that sharing keys defeats usage tracking and limits.

#2 Setting usage plan limits too high or too low without testing.

Wrong approach:

Assigning very high request quotas and rate limits without monitoring.

Correct approach:

Start with conservative limits and adjust based on real usage and performance data.

Root cause:

Lack of understanding of API capacity and user behavior leads to poor limit settings.

#3 Not securing API keys in client applications.

Wrong approach:

Embedding API keys directly in public mobile or web app code.

Correct approach:

Use backend proxy or secure vaults to keep API keys hidden from users.

Root cause:

Underestimating the risk of key exposure and unauthorized usage.

Key Takeaways

API keys identify who is calling an API but do not control how much they use it.

Usage plans set limits like rate limits and quotas to protect the API from overload.

Together, API keys and usage plans help manage access, ensure fairness, and enable monitoring.

Properly securing API keys and designing usage plans are essential to prevent abuse and downtime.

Advanced usage plans can cover multiple APIs and require careful management to avoid security and performance issues.

Practice

1. What is the main purpose of an API key in AWS API Gateway?

easy

A. To monitor server CPU usage

B. To store user data securely

C. To encrypt API responses

D. To identify and control who can access the API

Solution

1. Step 1: Understand API key role

   An API key is used to identify the client calling the API.

2. Step 2: Identify purpose in AWS API Gateway

   It helps control and track who can access the API, not data storage or encryption.

3. Final Answer:

   To identify and control who can access the API -> Option D

4. Quick Check:

   API key = identify and control access [OK]

Hint: API keys identify users, not store or encrypt data [OK]

Common Mistakes:

• Confusing API keys with encryption keys
• Thinking API keys store user data
• Assuming API keys monitor server metrics

2. Which of the following is the correct way to associate an API key with a usage plan in AWS API Gateway?

easy

A. Create a usage plan, then add the API key to it

B. Create an API key, then add a usage plan to it

C. Create a usage plan and API key separately without linking

D. Create an API key inside the usage plan settings

Solution

1. Step 1: Understand usage plan and API key relationship

   Usage plans define limits and must have API keys linked to enforce them.

2. Step 2: Correct linking process

   You create a usage plan first, then add API keys to it to apply limits.

3. Final Answer:

   Create a usage plan, then add the API key to it -> Option A

4. Quick Check:

   Usage plan first, then add API key [OK]

Hint: Link API keys by adding them to usage plans [OK]

Common Mistakes:

• Trying to add usage plans to API keys
• Not linking keys and plans at all
• Assuming API keys are created inside usage plans

3. Given this AWS CLI command output showing usage plan limits:

{"throttle": {"rateLimit": 100, "burstLimit": 200}, "quota": {"limit": 1000, "period": "DAY"}}

What does this usage plan enforce?

medium

A. Max 1000 requests per second, burst up to 200, and 100 requests per day

B. Max 200 requests per second, burst up to 100, and 1000 requests per day

C. Max 100 requests per second, burst up to 200, and 1000 requests per day

D. No limits on requests per second or daily quota

Solution

1. Step 1: Interpret throttle limits

   RateLimit 100 means 100 requests per second max, burstLimit 200 allows short bursts up to 200 requests.

2. Step 2: Interpret quota limits

   Quota limit 1000 per DAY means max 1000 requests allowed in one day.

3. Final Answer:

   Max 100 requests per second, burst up to 200, and 1000 requests per day -> Option C

4. Quick Check:

   Throttle = 100/sec + 200 burst, Quota = 1000/day [OK]

Hint: Throttle = per second, quota = daily limit [OK]

Common Mistakes:

• Mixing burstLimit with rateLimit
• Confusing quota limit with per second limit
• Ignoring the quota period

4. You created an API key and a usage plan, but API calls with the key are not limited by the usage plan. What is the most likely cause?

medium

A. The usage plan has no throttle or quota limits set

B. The API key is not associated with the usage plan

C. The API key is expired

D. The API Gateway stage is not deployed

Solution

1. Step 1: Check API key and usage plan link

   Usage plans only apply limits if the API key is linked to them.

2. Step 2: Verify other causes

   While no limits or deployment can cause issues, the key not linked means no limits apply.

3. Final Answer:

   The API key is not associated with the usage plan -> Option B

4. Quick Check:

   Key must be linked to usage plan for limits [OK]

Hint: Check if API key is linked to usage plan [OK]

Common Mistakes:

• Assuming usage plan limits apply without linking keys
• Ignoring deployment status
• Confusing expired keys with unlinked keys

5. You want to create a usage plan that limits users to 5000 requests per month and 50 requests per second with a burst of 100. You also want to track usage per API key. Which steps correctly achieve this?

hard

A. Create usage plan with quota 5000/month and throttle 50/sec burst 100, then add API keys to the plan

B. Create API keys with limits, then assign usage plan to each key

C. Create usage plan with limits, deploy API, no need to link API keys

D. Set limits on API Gateway stage, then create API keys without usage plan

Solution

1. Step 1: Define usage plan with required limits

   Set quota to 5000 per month and throttle to 50 requests per second with burst 100.

2. Step 2: Link API keys to usage plan

   Adding API keys to the usage plan enables tracking and enforcement of limits per key.

3. Final Answer:

   Create usage plan with quota 5000/month and throttle 50/sec burst 100, then add API keys to the plan -> Option A

4. Quick Check:

   Usage plan sets limits + keys linked for tracking [OK]

Hint: Set limits in usage plan, then add API keys [OK]

Common Mistakes:

• Trying to set limits on API keys directly
• Not linking API keys to usage plan
• Setting limits only on API Gateway stage