Authentication and Authorization Basics
Identification is useful because it gives the vendor a basis for managing consumption.
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…
The Missing Identity
When your application sends a request to a vendor's API, the vendor needs to know who is making the call. Without identification, the vendor cannot distinguish one user from another. That makes it impossible to track who is consuming the service or enforce usage policies. An API key supplies the connection between a request and the account that made it.
What do you think happens?
What information does a vendor lack when an API request arrives without an API key?
Reveal answer
Which user account made the request and how much service that account has consumed
The vendor uses the API key to identify the user, monitor service consumption, and enforce policies about usage.
From Request to User Account
An API key is a unique identifier included with an API request. Each key is associated with a user account. When the vendor's server receives the request, it extracts the key, looks it up in its database of valid keys, and validates it. If the key is found and valid, the server retrieves the associated user account information. The request is now connected to a known user.
- 1The client sends a request that includes an API key.
- 2The vendor's server extracts the key from the request.
- 3The server looks up the key in its database of valid keys.
- 4The server retrieves the associated user account when the key is valid.
- 5The vendor can process the request with knowledge of who is making the call.
Counting and Controlling Usage
Identification is useful because it gives the vendor a basis for managing consumption. After the request has been processed, the vendor increments the usage counter for the identified account. The vendor can therefore monitor how much service each user is consuming, track usage for billing, and enforce rate limits.
The sequence matters: the vendor first connects the request to an account, then records that account's usage. Because the request is identified, the vendor can apply policies to the correct user rather than treating all requests as one undifferentiated stream.
Service Tiers and Access Decisions
The identified account also tells the vendor which service tier applies. A vendor might offer a free tier with limited requests per day and a premium tier with higher limits. By associating the API key with the account, the vendor can determine whether a request fits that account's usage policy and can manage access to the appropriate service tier.
| Question | Identification | Policy and authorization |
|---|---|---|
| What does the vendor determine? | Which user account is making the call | What usage rules or service tier apply |
| What supports the decision? | A valid API key associated with an account | The account's limits, tier, and tracked usage |
| Why is it needed? | To connect activity to the correct user | To enforce limits and manage service access |
In this topic, the API key first supports user identification; that identification then gives the vendor a basis for applying usage policies and managing service tiers.
Separate Keys for Separate Applications
Tracing usage by application
A single user has one web application, one mobile application, and one data analysis script. Each application uses a different API key. How can the vendor tell which application is consuming the most resources?
- 1Connect each key
Each API key is associated with the same user account, but the keys are tracked independently.
- 2Record requests separately
Requests from the web application, mobile application, and data analysis script are attributed to their respective keys.
- 3Compare the tracked totals
The vendor can distinguish the consumption of each application instead of seeing only one combined total.
- 4Use the detail
The user can see which application consumes the most resources and can optimize accordingly. A key can also be revoked without affecting the other keys.
Independent keys provide granular monitoring of applications belonging to the same user account.
| Application | Requests | Tracking result |
|---|---|---|
| Web application | 1,250 | Tracked through its own API key |
| Mobile application | 3,840 | Tracked through its own API key |
The vendor can identify which application generated the requests because each application uses a different independently tracked key.
Mistakes Beginners Make
Common mistake Treating an API request as identifiable without an API key
What it looks likeAssuming the vendor can automatically know which user is responsible for an unmarked request
Why it failsWithout identification, the vendor cannot distinguish one user from another or track whose account consumed the service.
Do this insteadInclude the API key with requests so the vendor can look up the associated user account.
Common mistake Thinking an API key is used only to identify a user
What it looks likeUsing the key for account lookup but ignoring usage counters and service limits
Why it failsVendors also use API keys to monitor consumption, enforce rate limits, manage service tiers, and track usage for billing.
Do this insteadTreat identification as the first step in a larger usage-management process.
Common mistake Combining every application under one indistinguishable tracking identity
What it looks likeUsing one shared key for a web application, mobile application, and data analysis script when separate monitoring is needed
Why it failsThe vendor cannot independently track which application is consuming resources if the applications do not use separate keys.
Do this insteadUse separate API keys when independent application-level tracking is useful.
Common mistake Ignoring rate limits when designing an API client
What it looks likeBuilding an application that assumes every request will always be accepted
Why it failsService tiers can have different request limits, and an application may exceed the applicable limit.
Do this insteadPlan for rate limits and implement error handling for cases in which the limit is exceeded.
Design Notes for API Clients
When designing an application that uses a vendor API, plan for how you will obtain, store, and use the API key. Also anticipate rate limits and implement error handling for cases in which the application exceeds them. These decisions connect the application's request behavior to the vendor's identification and usage-management process.
- Know which account the API key represents.
- Understand that the vendor validates the key on each request.
- Expect usage to be monitored after the account is identified.
- Account for the limits associated with the applicable service tier.
- Use separate keys when independent application tracking is useful.
- Plan error handling for requests that exceed a rate limit.
Check Your Understanding
A user has a free-tier account and two applications. The user gives each application its own API key. Explain the sequence that allows the vendor to identify each application, track its requests, and apply the user's service-tier limits.
Hints
- Start with what the client includes in each request.
- Explain how the vendor connects each key to the user account.
- Mention independent tracking for the two applications.
- Finish by explaining how the account's service tier affects usage decisions.
Key Takeaways
- 1An API key connects an API request to the user account associated with that key.
- 2The vendor validates the key on each request and uses it to identify the caller.
- 3Once the caller is identified, the vendor can monitor usage, enforce rate limits, and track usage for billing.
- 4The associated account tells the vendor which service tier and usage policies apply.
- 5One user can own multiple independently tracked keys for different applications.
At a glance
- API keys solve the vendor's need to identify who is making an API request.
- A valid key is looked up and connected to an associated user account.
- That identity enables usage monitoring, rate limiting, service-tier management, and billing tracking.
- Separate keys let one user monitor different applications independently.
- API clients should anticipate rate limits and handle cases in which usage limits are exceeded.