Understanding HTTP Requests and Responses
API keys can be included in requests via two methods: as a URL query parameter or as part of POST data.
The Key's Destination
An API key is a unique identifier that proves you have permission to use an API. When you make a request to a protected API, the key must travel with the request so the server can verify who you are and whether you may access the requested resource. Without the required key, the API will reject the request. The practical question is where the key belongs inside the request.
The two primary locations are the URL query string and the body of a POST request.
What do you think happens?
An API requires a key as a URL parameter. Where would you expect the key to appear?
Reveal answer
Answer: In the URL after a question mark
A URL parameter is added as a query string. The query string begins with a question mark and contains a parameter name, an equals sign, and the key value.
Two Locations in One Request
The API designer determines how the key must be transmitted. One API may require the key in the URL, another may require it in POST data, and another may accept either location. These are structurally different requests: a URL-parameter request places the key in the address being requested, while a POST-data request places the key in the request body. The documentation for the API is the authority; the client does not freely choose a different location.
| Method | Key location | Typical request structure |
|---|---|---|
| URL query parameter | The URL query string | Endpoint followed by ?api_key=key-value |
| POST data | The request body | POST body containing api_key=key-value or a JSON object with the key |
The structural difference is whether the URL or the request body carries the API key.
Tracing the Key
One key, two possible paths
An API endpoint is https://api.example.com/data and the API key is abc123xyz. Show the two request structures described by the API documentation.
URL parameter: Append a query string to the endpoint. The full URL becomes https://api.example.com/data?api_key=abc123xyz.
POST data: Keep the key out of the URL and place it in the POST request body. The body may contain api_key=abc123xyz or, in JSON format, {"api_key": "abc123xyz"}.
Documentation check: Use only the structure required by the API designer. A correctly formed request using the wrong location may not satisfy the API's requirements.
The same API key can be represented in either location, but the API specification determines which representation is valid for that API.
In the URL method, the key becomes part of the address sent to the server. In the POST method, the key becomes part of the request payload instead. The server still receives the key in both cases, but it receives it from a different part of the request.
Visibility and Protection
URL parameters are visible in the address bar, browser history, and server logs. This makes an accidentally copied or shared URL a possible source of key exposure. POST data is hidden from casual observation in the URL because it is placed in the request body, but it is still transmitted over the network. Hiding the key in the body does not make the transmission automatically secure.
Following the API Specification
The correct choice is not simply the method that seems more convenient. First read the API documentation and identify the required location. If the API requires a URL parameter, place the key in the URL. If it requires POST data, place the key in the request body. If it accepts either, prefer POST data when possible because it is less likely to be accidentally exposed through browser history, server logs, or shoulder surfing. In every case, use HTTPS.
Never share a URL or request that contains your API key. If you accidentally expose a key or suspect that it has been compromised, regenerate it immediately and update the applications that use it. Do not leave an exposed key active.
Common Transmission Mistakes
Putting the key in the URL when the API requires POST data.
The API designer specifies the accepted location. A key in the wrong part of the request may not satisfy the API's requirements.
Fix:
Follow the documentation and place the key in the POST request body.Assuming POST data is automatically secure.
POST data is still transmitted over the network. Neither method is truly secure without HTTPS encryption.
Fix:
Use HTTPS for the entire connection.Treating a URL containing a key as safe to share.
URL parameters can be visible in browser history and server logs, and the shared URL itself contains the key.
Fix:
Do not share requests containing keys. If the key was exposed, regenerate it immediately.Choosing a method without reading the API documentation.
Different APIs have different requirements, and the API designer decides which method must be used.
Fix:
Read the API specification before constructing the request.
Practice the Decision
An API's documentation says that the key must be included in the request body and that the connection must use HTTPS. Describe where you would place the key, what you would avoid putting in the URL, and which transport requirement you would verify.
Hints
- The request body is the location used for POST data.
- A key in the URL can appear in the address bar, browser history, and server logs.
- HTTPS protects the data in transit.
Checking your decision
The documentation accepts either a URL parameter or POST data. Which method should you prefer when both are valid?
Compare exposure: A URL parameter is 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 through those locations.
Apply the security condition: The connection must still use HTTPS because POST data is transmitted over the network and neither method is secure without encryption.
Make the selection: Prefer POST data when possible, while continuing to follow any specific requirement in the API documentation.
When an API accepts either method, POST data is generally the preferred choice, together with HTTPS.
Key Takeaways
- An API key identifies the caller and must accompany every request to a protected API.
- A URL parameter places the key in the query string after a question mark; POST data places it in the request body.
- URL parameters are more visibly exposed through locations such as the address bar, browser history, and server logs.
- POST data is less likely to be accidentally exposed in those locations, but it still requires HTTPS encryption.
- The API designer decides which method is valid, so always follow the API documentation exactly.
- If a key is exposed, regenerate it immediately and update applications that use it.
Key Takeaways
- API keys can be transmitted as URL query parameters or as POST data.
- The key appears in the URL in the first method and in the request body in the second.
- URL parameters are more visible, while POST data is less likely to be exposed casually.
- Neither method is secure without HTTPS.
- The API documentation determines the required method; when either method is accepted, prefer POST data when possible.