Authentication and Authorization Basics

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.

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.

1. The client sends a request that includes an API key.
2. The vendor's server extracts the key from the request.
3. The server looks up the key in its database of valid keys.
4. The server retrieves the associated user account when the key is valid.
5. The 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.

Separate Keys for Separate Applications

Mistakes Beginners Make

• Treating an API request as identifiable without an API key

  Without identification, the vendor cannot distinguish one user from another or track whose account consumed the service.

  Fix: Include the API key with requests so the vendor can look up the associated user account.

• Thinking an API key is used only to identify a user

  Vendors also use API keys to monitor consumption, enforce rate limits, manage service tiers, and track usage for billing.

  Fix: Treat identification as the first step in a larger usage-management process.

• Combining every application under one indistinguishable tracking identity

  The vendor cannot independently track which application is consuming resources if the applications do not use separate keys.

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

• Ignoring rate limits when designing an API client

  Service tiers can have different request limits, and an application may exceed the applicable limit.

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

Key Takeaways

1. An API key connects an API request to the user account associated with that key.
2. The vendor validates the key on each request and uses it to identify the caller.
3. Once the caller is identified, the vendor can monitor usage, enforce rate limits, and track usage for billing.
4. The associated account tells the vendor which service tier and usage policies apply.
5. One user can own multiple independently tracked keys for different applications.