Secure Credential Storage and Environment Variables
API keys are the mechanism vendors use to identify users and monitor their service consumption.
The Identity Problem
When an application sends a request to a vendor's API, the vendor needs to know who is making the request. 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 solves this identity problem by acting as a unique identifier included with the request.
An API key can be understood as a membership card. When the card is presented, the vendor can look up the associated account and connect the activity to that account. Without the card, the vendor has no way to connect the activity to a particular account.
An API key is not merely an extra piece of request data. It gives the vendor the information needed to associate a request with a user account.
From Application to Account
The vendor-side sequence begins when a client sends a request containing the API key. The vendor's server receives the request and extracts the key. The key may be included in request headers, query parameters, or the request body. The server then looks up the key in its database of valid keys. If the key is found and valid, the server retrieves the associated user account information. The request is now connected to an identified user.
What Identification Enables
API keys serve three connected purposes for vendors. They identify who is using the service, allow the vendor to monitor how much each user is using, and provide a foundation for enforcing policies and managing service tiers.
| Vendor need | How the API key helps |
|---|---|
| Identify the requester | The key is associated with a user account and is validated on each request. |
| Monitor consumption | The vendor can record usage for the identified account and key. |
| Enforce rate limits | The vendor can apply limits to the account's requests. |
| Manage service tiers | The vendor can determine whether the account is on a free or premium tier and apply the relevant limits. |
| Track billing usage | The vendor can track usage for billing and identify when a user may be approaching a billing threshold. |
The vendor uses identification to connect requests with account-level policies and usage records.
After identifying the user, the vendor can process the request with knowledge of who is making the call. After processing, the vendor increments a usage counter to record that another request was made and then sends the response back to the client. Usage information can also help the vendor understand service usage patterns, plan infrastructure capacity, and identify when a user may be approaching a billing threshold.
Limits and Service Tiers
A service tier is a set of service conditions associated with an account. A vendor might provide a free tier with a limited number of requests per day and a premium tier with higher limits. The API key lets the vendor connect the request to the account and determine which tier applies. The vendor can then enforce the relevant usage policy, including rate limits.
Rate limiting is not separate from identification. The vendor first needs to know which account is making the request before it can apply that account's usage limits or service tier.
Multiple Keys, Separate Records
Separating Web and Mobile Usage
A user has one web application and one mobile application. The web application makes 1,250 requests, while the mobile application makes 3,840 requests. How can the vendor tell which application generated each request?
Assign separate keys: The user uses one API key for the web application and another API key for the mobile application.
Validate each request: Each request includes the key used by its application, and the vendor validates that key on the request.
Track independently: Because the keys are tracked independently, the vendor can connect the 1,250 web requests and the 3,840 mobile requests to their respective applications.
Use the records: The separate records show which application consumes more resources and help the user optimize accordingly.
The user account owns multiple keys, but the vendor can still distinguish usage by application because each key is tracked independently.
Storage Before Sending
Secure credential storage is part of the application design that surrounds API use. Before building an integration, plan how the application will obtain, store, and use its API key. In an environment-variable approach, the application obtains the key from the environment-variable storage step and then uses it when constructing the API request. The vendor still receives and validates the key as part of the request.
Common Credential Mistakes
Treating the API key as optional identification
Without identification, the vendor cannot distinguish one user from another or connect the request to an account.
Fix:
Design the request so that it includes the API key and plan how the application obtains and stores that key.Using one key for every application without considering separate tracking
The vendor cannot use independently tracked keys to show which application is consuming the most resources.
Fix:
Use separate keys when granular monitoring or independent revocation is useful.Ignoring service tiers and usage limits
Vendors use API keys to enforce rate limits and manage free and premium tiers.
Fix:
Anticipate rate limits and implement error handling for cases where the application exceeds them.Planning the request but not the credential's storage
The application still needs a plan for obtaining, storing, and using its API key.
Fix:
Treat credential storage, including the environment-variable approach, as part of the integration design.
Practice the Trace
A vendor receives a request with a key. Describe the sequence from receiving the request to returning a response. Then explain how the sequence would support rate limiting and usage monitoring.
Hints
- Begin with extracting the key from the request.
- Include the lookup in the database of valid keys and the associated user account.
- Include usage-counter updates after processing.
- Connect the identified account to its service tier and usage policy.
What do you think happens?
A user has separate keys for a web application and a mobile application. If the web application makes 1,250 requests and the mobile application makes 3,840 requests, can the vendor identify which application generated each set of requests?
Reveal answer
Answer: Yes, because each key is tracked independently.
A single user can own multiple API keys, and each key can be tracked independently. This lets the vendor distinguish usage by application while still associating the keys with the same user account.
The Complete Model
The complete model is a chain: the application obtains and stores an API key, includes it in a request, and sends that request to the vendor. The vendor extracts and validates the key, looks up the associated user account, applies the relevant service policies, processes the request, updates usage information, and returns a response. Environment variables belong to the storage part of this design, while API-key validation, monitoring, rate limiting, and service-tier management occur on the vendor side.
- An API key identifies the user account associated with an API request.
- The vendor validates the key on every request and uses it to retrieve account information.
- Identification allows the vendor to monitor consumption, enforce rate limits, and track usage for billing.
- A key connects the request to the user's service tier, such as a free tier with lower limits or a premium tier with higher limits.
- Multiple independently tracked keys let one user separate usage by application and revoke one key without affecting the others.
- Applications should plan how they obtain, store, and use API keys, including the use of environment variables as a credential-storage step.
Key Takeaways
- API keys solve the vendor's problem of identifying who is making each request.
- After validation, the vendor can connect a request to an account, apply usage policies, and record consumption.
- Rate limits, billing tracking, and free or premium service tiers depend on associating requests with accounts.
- Separate API keys allow independent monitoring of different applications owned by the same user.
- Secure credential handling requires planning how the application obtains, stores, and uses its key.