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.