HTTP Request Headers and Query Parameters
The API key is not merely a value attached to a request. It connects the request to an account, allowing the vendor to identify the caller, record usage, apply rate limits, manage service tiers, and track usage for billing.
The Identity Problem
When your client sends a request to a vendor's API, the vendor needs a way to know who is making the call. Without identification, the vendor cannot distinguish one user from another. That makes it impossible to track which account is consuming the service or to enforce usage policies for that account.
An API key is a unique identifier that you include with an API request to tell the vendor who you are. Each API key is associated with a user account and is validated on every request.
A useful analogy is a membership card. When you present the card to a vendor, the vendor can look up your account and keep track of what you are doing. An API key serves a similar identification purpose for requests sent to an API.
Request Path to Account
An API key travels as part of the request sent by your client. The source identifies request headers, query parameters, and the request body as places where a vendor may extract the key. This article focuses on the first two locations: headers and query parameters.
The vendor's server receives the request and extracts the API key. It then looks up the key in its database of valid keys. If the key is found and is valid, the server retrieves the associated user account. The request is now connected to an identified account rather than being an unattributed call.
Headers and Query Parameters
| Request location | What the source establishes | Vendor action |
|---|---|---|
| Request headers | An API key may be included here | The vendor extracts and validates the key |
| Query parameters | An API key may be included here | The vendor extracts and validates the key |
Headers and query parameters are two request locations from which a vendor may obtain an API key.
The important idea is not that the key is a separate request. The key travels with the request, and the vendor extracts it from the location expected by that API. Whether the key is placed in a header or a query parameter, the vendor uses it to look up the associated account and validate the request.
Validation and Usage Tracking
After identifying the account, the vendor can process the request with knowledge of who is using the service. After processing, the vendor increments the usage counter so that the request becomes part of the account's usage record.
The counter gives the vendor a record of how much the identified account has used the service. Vendors use this information to enforce rate limits, monitor overall usage, track usage for billing, and identify when an account may be approaching a billing threshold.
Multiple Keys and Service Tiers
Separating Application Usage
A single user owns a web application, a mobile application, and a data analysis script. The user assigns a different API key to each application.
- 1Identify the account
Each key is associated with the same user account, so the vendor can identify the user behind every request.
- 2Track keys independently
Because each application uses a different key, the vendor can track the requests from the web application, mobile application, and analysis script separately.
- 3Compare usage
Independent tracking shows which application is consuming the most resources and helps the user optimize usage.
- 4Apply account policies
The vendor can use the identified account and its service rules when enforcing limits, managing tiers, or tracking usage for billing.
Multiple API keys allow more granular monitoring within one user account. A key can also be revoked without affecting the other keys.
Service tiers are another reason the key matters. A vendor might offer a free tier with limited requests per day and a premium tier with higher limits. The API key lets the vendor determine which account and tier are connected to the request, then apply the relevant usage policies.
Common Misunderstandings
Common mistake Assuming the vendor can track usage without identifying the caller.
What it looks likeSending requests without including the API key expected by the vendor.
Why it failsWithout identification, the vendor cannot connect the request to a user account or distinguish one user's consumption from another's.
Do this insteadInclude the API key with the request in the location specified by the vendor, such as a request header or query parameter.
Common mistake Treating all API keys owned by one user as one independently tracked key.
What it looks likeUsing separate keys for a web application and mobile application but expecting the vendor to report them as the same application.
Why it failsA single user can own multiple API keys, and each key is tracked independently.
Do this insteadUse the independent key records to understand which application is consuming resources.
Common mistake Ignoring rate limits and service tiers after obtaining a valid key.
What it looks likeAssuming that a valid key automatically permits unlimited requests.
Why it failsVendors use API keys to enforce rate limits and manage free and premium service tiers.
Do this insteadPlan for rate limits and implement error handling for situations in which usage exceeds the applicable limit.
Common mistake Assuming the key's location is interchangeable for every API.
What it looks likePutting a key in a query parameter when the vendor's API expects it in a request header.
Why it failsThe vendor extracts the key from the location expected by its API.
Do this insteadFollow the vendor's specified request format.
Applying the Model
A vendor receives three requests: two use one API key and one uses a second API key belonging to the same user account. Explain what the vendor can identify, what it can track separately, and how the account's service tier could affect request policies.
Hints
- Start with the relationship between an API key and a user account.
- Remember that multiple keys belonging to one account can be tracked independently.
- Connect the identified account to rate limits and service tiers.
What do you think happens?
A user has one API key for a web application and another for a mobile application. If the web application makes 1,250 requests and the mobile application makes 3,840 requests, which application can the vendor identify as using more resources?
Reveal answer
The mobile application.
Each key is tracked independently, so the vendor can associate the two usage totals with their respective applications.
Practical Design Notes
When building an application that uses a vendor API, plan how you will obtain, store, and use the API key. Also anticipate the vendor's rate limits and implement error handling for situations in which those limits are exceeded. If you use multiple keys for different applications, independent tracking can help you see which application is consuming the most resources.
The API key is not merely a value attached to a request. It connects the request to an account, allowing the vendor to identify the caller, record usage, apply rate limits, manage service tiers, and track usage for billing.
Key Takeaways
- An API key identifies the user account associated with an API request.
- A vendor can extract and validate the key from a request header, query parameter, or, depending on the API, the request body.
- After identifying the account, the vendor can record usage, enforce rate limits, and track usage for billing.
- Free and premium service tiers can have different request limits, and the API key connects a request to the applicable account policies.
- Multiple keys owned by one user can be tracked independently, allowing usage to be separated by application.