Introduction to APIs and Web Services
API keys can be included in requests via two methods: as a URL query parameter or as part of POST data.
A Request Needs Identity
An API key is a unique identifier that proves you have permission to use an API. When you request a protected resource, the server uses the key to verify who you are and whether you are allowed to access that resource. Without the required key, the API will reject the request.
What do you think happens?
Where can an API key be placed when an API requires it?
Reveal answer
Answer: In the URL as a query parameter or in POST data
These are the two primary methods described for including an API key in an API request. The API designer determines which method the API accepts.
Two Transmission Locations
The key question is not whether the request needs an API key, but where the key belongs within the request. One method places it in the URL as a query parameter. The other places it in the body of a POST request as part of the submitted data. These methods have different structures and different exposure risks.
Following the Key Through a Request
The client begins with the same goal in both cases: send a request that contains a key the API can verify. The difference is the request location. The URL method carries the key in the address, while the POST method carries it in the request body. The API server then checks the key according to the API's design.
Visibility and Protection
| Method | Key location | Exposure described in the source | Important requirement |
|---|---|---|---|
| URL parameter | URL query string | Visible in the address bar, browser history, and server logs | Use it when the API specification requires it |
| POST data | HTTP request body | Hidden from the URL and less likely to be accidentally exposed through browser history, server logs, or shoulder surfing | Use it when the API specification allows or requires it |
Reading the API Specification
- Read the API documentation before constructing the request.
- Check whether the documentation requires the key in a URL parameter, in POST data, or accepts either location.
- Place the key exactly where the API specification says it belongs.
- Use HTTPS for the complete connection regardless of which method is required.
- If POST data is permitted, prefer it when possible because it is less likely to be accidentally exposed through browser history, server logs, or shoulder surfing.
Worked Request Comparison
Placing the Same Key in Two Locations
An API uses the endpoint https://api.example.com/data and the key value abc123xyz. Show the structural difference between the two supported transmission methods.
URL parameter: Append a query string to the endpoint: https://api.example.com/data?api_key=abc123xyz. The key is part of the URL.
POST data: Keep the key out of the URL and place it in the POST request body, for example as form data api_key=abc123xyz or as JSON {"api_key": "abc123xyz"}.
Security check: The URL version exposes the key in the address bar, browser history, and server logs. The POST version hides it from the URL, but both methods still require HTTPS.
Specification check: Use the version required by the API documentation. If the documentation requires a URL parameter, use the URL version; if it requires POST data, use the body version.
The key value is the same, but its structural location changes: URL query string for one method and POST request body for the other.
Mistakes That Expose Keys
Putting the key in the URL when the API requires POST data
The API designer specifies the accepted location. A request that does not follow that specification may not be accepted.
Fix:
Read the documentation and place the key exactly where the API requires it.Assuming POST data is secure without HTTPS
POST data is hidden from the URL but is still transmitted over the network. Neither method is secure without HTTPS encryption.
Fix:
Use HTTPS whenever transmitting an API key.Sharing a URL that contains an API key
URL parameters are visible in the address bar, browser history, and server logs.
Fix:
Do not share URLs or requests that contain an API key.Leaving an exposed key active
An exposed key may be compromised.
Fix:
Regenerate the key immediately and update applications that use it.
Practice the Decision
An API documentation page says that the key must be sent as part of POST data. The endpoint is https://api.example.com/data, and the key is abc123xyz. Decide whether the key belongs in the URL or in the request body, then state why HTTPS is still required.
Hints
- Look for the location named by the API documentation.
- POST data is sent in the request body rather than in the URL.
- The source distinguishes where the key is placed from how the connection is protected.
- The key belongs in the request body because the API specification requires POST data. HTTPS is still required because POST data is hidden from the URL but remains transmitted over the network, and neither transmission method is secure without HTTPS encryption.
Key Takeaways
- An API key identifies a caller and allows the API server to verify permission for a protected resource.
- The two primary transmission methods are a URL query parameter and POST data in the request body.
- URL parameters are visible in the address bar, browser history, and server logs; POST data is hidden from the URL and is less likely to be accidentally exposed in those places.
- Neither method is secure without HTTPS encryption.
- The API designer decides where the key must go, so always follow the API documentation exactly.