OAuth and Token-Based Authentication
The server then looks up the key in its database of valid keys.
Try it: Rate Limits, 429 and Retries
How an API enforces a per-key rate limit (token bucket or fixed window), answers 429 Too Many Requests with Retry-After, and how a client's retry policy — exponential backoff with a cap, honouring Retry-After, and a timeout for slow responses — decides when each request finally succeeds or gives up.
How it works
- The server reads the API key and looks it up; an unknown key gets 401 and uses no quota.
- Each known key has its own limiter: a token bucket (one token per request, refilled at a fixed rate up to the capacity) or a fixed window (at most L requests per window).
- With no quota left the server answers 429 with Retry-After: the whole seconds until quota returns.
- The client waits min(cap, base × multiplier^(attempt-1)) — or longer, if Retry-After says so — and retries 429s and timeouts up to the maximum number of attempts; a 401 is never retried.
- A response slower than the client's timeout counts as a failed attempt even though the server did the work.
Default run (15 steps): 8 requests are scheduled. The server gives each API key its own token bucket (capacity 3, +1 token every 1.00 s); the client retries 429s and timeouts up to 4 attempts in total. … All requests finished by 6.70 s. 7/8 succeeded · 0 gave up · 1 unauthorized · 13 attempts (3× 429, 2× timeout).
Simplified: Deterministic model on a simulated millisecond clock: fixed server latency (longer inside one slow period), no jitter in the backoff, no network delay for the request itself, and two API keys plus one invalid key. Real APIs vary in how they compute Retry-After and which errors they retry.
Loading the simulation…
Why Identification Matters
When your application sends a request to a vendor's API, the vendor needs to know who is making that request. If the request contains no identifying information, the vendor cannot distinguish one user from another. That makes it impossible to connect service consumption to a particular account or enforce account-specific usage policies.
An API key is a unique identifier included with an API request. The vendor uses that identifier to look up an associated user account. In this way, the key connects an otherwise separate request to an account the vendor can recognize and monitor.
Think of an API key like a membership card. When you present the card, the vendor can look you up in its system, see your account details, and keep track of what you are doing. Without the card, the vendor has no way to connect your actions to your account.
The Request Validation Path
The vendor processes an API-key request through a sequence of steps. Your client sends a request containing the key. The vendor's server receives the request and extracts the key, typically from request headers, query parameters, or the request body. The server then looks up the key in its database of valid keys.
Tracing one request
A client sends a request containing an API key. What does the vendor do with that key?
- 11. Receive
The vendor's server receives the request from the client.
- 22. Extract
The server extracts the API key from the request. The key may be in the request headers, query parameters, or body.
- 33. Validate
The server looks up the key in its database of valid keys.
- 44. Identify
If the key is found and valid, the server retrieves the associated user account information.
- 55. Process and record
The server processes the request with knowledge of who is making it and increments the user's usage counter.
- 66. Respond
The server sends the response back to the client.
The API key turns an unidentified request into a request associated with a known user account and a usage record.
Validation happens on every request. When the key is found and valid, the vendor retrieves the associated account information before processing the request. After processing, the vendor increments the usage counter and then sends the response back to the client. The key therefore participates in both identification before processing and usage tracking after processing.
Three Jobs of an API Key
API keys serve three connected purposes for vendors. First, they identify who is using the service. Second, they enable the vendor to monitor how much that user is using. Third, they provide the foundation for enforcing policies and managing service tiers.
- Identification: the key is associated with a user account, so the vendor can determine who is making the call.
- Usage monitoring: the vendor can record requests and increment a usage counter for the identified account or key.
- Policy enforcement: the vendor can apply rate limits, service-tier rules, and billing-related tracking to the request.
Usage monitoring is broader than simply counting requests. Vendors use usage data to understand how their services are being used, plan infrastructure capacity, and identify when a user might be approaching a billing threshold.
From Usage Record to Limit Decision
Once the vendor has identified the requester, it can record the request against that identity. That record supports decisions about whether the request fits the user's permitted usage. Rate limiting is one such policy: vendors use API keys to enforce limits on service consumption.
The source describes the usage sequence as an increment to the usage counter after the request is processed. It also emphasizes that applications should anticipate rate limits and implement error handling for cases in which a limit is exceeded. The important design relationship is that the vendor needs an identified account or key before it can meaningfully attribute consumption and apply account-specific policies.
Service Tiers and Account Policies
Vendors may offer different service tiers. For example, a free tier may have limited requests per day, while a premium tier may have higher limits. The API key is how the vendor connects an incoming request to the account whose tier and usage rules should be considered.
| Vendor decision | How the API key contributes |
|---|---|
| Identify the requester | The key is associated with a user account. |
| Monitor consumption | Requests can be recorded and usage counters incremented. |
| Apply rate limits | The vendor can enforce usage policies for the identified account. |
| Manage service tiers | The vendor can connect the request to a free or premium account tier. |
| Track billing usage | The vendor can track usage for billing and identify approach to a billing threshold. |
The main vendor decisions enabled by API-key identification
Separate Keys for Separate Applications
A single user account can own multiple API keys, and each key can be tracked independently. This makes it possible to distinguish usage by application rather than combining every request from the account into one undifferentiated total.
Comparing application usage
A user has one API key for a web application and another for a mobile application. The web application makes 1,250 requests, while the mobile application makes 3,840 requests. What can the vendor determine?
- 1Track the web key
The vendor records 1,250 requests under the key used by the web application.
- 2Track the mobile key
The vendor records 3,840 requests under the key used by the mobile application.
- 3Compare independently
Because the keys are different and tracked independently, the vendor can determine which application generated which requests.
- 4Use the information
The user can see which application consumes more resources and use that information to optimize accordingly.
The vendor can distinguish the web application's 1,250 requests from the mobile application's 3,840 requests instead of treating them as indistinguishable account activity.
Independent tracking also means that a key can be revoked without affecting the other keys. For example, a key used by a web application can be managed separately from keys used by a mobile application or a data analysis script.
Mistakes Beginners Make
Common mistake Treating an API key as unrelated to usage tracking
What it looks likeThinking the key only tells the vendor that a request is allowed.
Why it failsThe vendor validates the key to identify the user, then uses that identity to increment usage counters, enforce rate limits, manage service tiers, and track billing usage.
Do this insteadThink of the key as the link between the request, the account, and the vendor's usage policies.
Common mistake Assuming the vendor can enforce user-specific limits without identifying the user
What it looks likeSending requests without an identifying key and expecting the vendor to know which account should receive the usage record.
Why it failsWithout identification, the vendor cannot distinguish one user from another or connect consumption to a particular account.
Do this insteadInclude the API key with requests that need to be associated with the user account.
Common mistake Combining all application activity into one tracking category
What it looks likeUsing one key for a web application, mobile application, and data analysis script when separate tracking is needed.
Why it failsThe vendor cannot use the key to distinguish those applications if they all send requests through the same key.
Do this insteadUse separate keys when independent application-level monitoring is useful.
Common mistake Ignoring rate-limit handling
What it looks likeDesigning an application that assumes every request will always be accepted.
Why it failsThe source identifies rate limits as a practical consequence of API-key-based usage policies.
Do this insteadAnticipate rate limits and implement error handling for cases in which usage limits are exceeded.
Application Design Notes
When designing an application that uses a vendor API, plan how the application will obtain, store, and use its API key. The source also highlights the need to anticipate rate limits and implement error handling for situations in which usage limits are exceeded.
Check Your Understanding
A vendor offers a free tier with limited requests per day and a premium tier with higher limits. Explain why the vendor needs an API key on an incoming request before it can apply the appropriate usage policy.
Hints
- Start with what the vendor must know about the requester.
- Then connect the user account to its service tier.
- Finally explain how the vendor can compare recorded usage with the applicable limit.
A user has separate keys for a web application and a data analysis script. The web application makes 1,250 requests and the script makes 3,840 requests. What does independent key tracking allow the vendor and the user to determine?
Hints
- Look at what information is preserved when each application uses a different key.
- Identify which application generated each request count.
- Consider how that information could guide optimization.
Key Takeaways
- 1An API key is a unique identifier that connects an API request to a vendor-recognized user account.
- 2The vendor validates the key on every request, retrieves the associated account information, processes the request, increments usage, and returns a response.
- 3API keys let vendors identify users, monitor consumption, enforce rate limits, manage free and premium tiers, and track usage for billing.
- 4One user can own multiple independently tracked keys, allowing usage from separate applications to be distinguished and managed separately.
- 5Applications that use vendor APIs should plan how they obtain, store, and use keys and should handle situations in which rate limits are exceeded.
At a glance
- API keys solve the vendor's identification problem by linking each request to a user account.
- The vendor validates the key, retrieves account information, processes the request, and records usage.
- Recorded identity and usage support rate limiting, service-tier management, infrastructure planning, and billing tracking.
- Separate keys allow a single user to monitor different applications independently.
- Reliable API clients should anticipate usage limits and implement appropriate error handling.