OAuth and Token-Based Authentication

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.

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.

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.

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.

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

• Treating an API key as unrelated to usage tracking

  The 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.

  Fix: Think of the key as the link between the request, the account, and the vendor's usage policies.

• Assuming the vendor can enforce user-specific limits without identifying the user

  Without identification, the vendor cannot distinguish one user from another or connect consumption to a particular account.

  Fix: Include the API key with requests that need to be associated with the user account.

• Combining all application activity into one tracking category

  The vendor cannot use the key to distinguish those applications if they all send requests through the same key.

  Fix: Use separate keys when independent application-level monitoring is useful.

• Ignoring rate-limit handling

  The source identifies rate limits as a practical consequence of API-key-based usage policies.

  Fix: Anticipate 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

Key Takeaways

1. An API key is a unique identifier that connects an API request to a vendor-recognized user account.
2. The vendor validates the key on every request, retrieves the associated account information, processes the request, increments usage, and returns a response.
3. API keys let vendors identify users, monitor consumption, enforce rate limits, manage free and premium tiers, and track usage for billing.
4. One user can own multiple independently tracked keys, allowing usage from separate applications to be distinguished and managed separately.
5. Applications that use vendor APIs should plan how they obtain, store, and use keys and should handle situations in which rate limits are exceeded.