HTTPS and Secure Communication
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 request a protected resource, the key must travel with the request so the server can verify who you are and whether you are allowed to access that resource. The practical question is where the key belongs inside the request.
There are two primary locations: the key can be added to the URL as a query parameter, or it can be placed in the body of a POST request. These methods are structurally different, and their visibility is different, but neither method protects the key during transmission without HTTPS.
Two Request Structures
With a URL parameter, the key is appended to the endpoint as a query string. The query string begins with a question mark, followed by the parameter name, an equals sign, and the key value. A request might therefore use the URL https://api.example.com/data?api_key=abc123xyz.
With POST data, the key is sent in the HTTP request body rather than in the URL. The body may use form data, such as api_key=abc123xyz, or JSON, such as {"api_key": "abc123xyz"}. The key is not displayed in the URL itself.
Placing the Same Key in Two Ways
An API endpoint is https://api.example.com/data and the API key is abc123xyz. Show the two primary locations where the key may be included.
URL parameter: Append a query string to the endpoint: https://api.example.com/data?api_key=abc123xyz.
POST data: Keep the key out of the URL and place it in the request body, such as api_key=abc123xyz or {"api_key": "abc123xyz"}.
Structural difference: The first method places the key in the URL. The second places it in the body of a POST request.
Both methods transmit the key with the request, but the key occupies different parts of the request.
Visibility and Exposure
The main difference between the methods is visibility. A URL parameter is visible in the address bar, browser history, and server logs because the key is part of the URL. POST data is hidden from the URL and is placed in the request body, so it is less likely to be exposed through those URL-related locations. However, POST data is still transmitted over the network and is not automatically secure.
When an API allows a choice, prefer POST data when possible because it is less likely to be accidentally exposed through browser history, server logs, or shoulder surfing. This preference does not override the API documentation: if the API requires the key in the URL, you must use the URL method.
HTTPS During Transmission
Both URL parameters and POST data carry the API key across a network. Neither method is secure without HTTPS encryption. Always use HTTPS when transmitting an API key so the connection protects the data in transit.
Following the API Specification
The API designer decides where the key must go. Some APIs require a URL parameter, some require POST data, and some accept either location. The API documentation explicitly states the required method, so you do not choose based only on personal preference.
- Read the API documentation to identify where the key must be placed.
- Put the key in the specified location: the URL query string or the POST request body.
- Use HTTPS for the complete connection whenever transmitting the key.
- Avoid sharing URLs or requests that contain the key.
- If you suspect that the key was exposed, regenerate it immediately and update applications that use it.
Common Placement Mistakes
Putting the key wherever you prefer instead of following the API documentation.
The API designer specifies the required location, and the server may reject a request that uses the wrong method.
Fix:
Follow the API specification exactly.Assuming POST data is automatically secure.
POST data is hidden from the URL but is still transmitted over the network.
Fix:
Use HTTPS for either key-transmission method.Treating a URL parameter as harmless because the request is simple.
URL parameters are visible in the address bar, browser history, and server logs.
Fix:
Avoid sharing URLs containing keys, and prefer POST data when the API allows it.Leaving an exposed key active.
An exposed key may be compromised.
Fix:
Regenerate the key immediately and update applications that use it.
Choose the Transmission Method
Generated scenario: An API documentation page says that its key must be sent as a URL query parameter. Decide where the key belongs, identify one place where it may be visible, and state what connection security is required.
Hints
- Look for the method named by the API documentation.
- Ask whether the key is part of the URL or the request body.
- Remember that both methods require HTTPS.
Generated scenario: Another API accepts the key in either a URL parameter or POST data. Which location should you prefer, and why might that choice reduce accidental exposure?
Hints
- Compare the visibility of a URL with the visibility of request-body data.
- Consider browser history, server logs, and the address bar.
- Do not forget that HTTPS is still required.
Key Takeaways
- An API key can be sent as a URL query parameter or in the body of a POST request.
- 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 URL-related locations, but it is still transmitted over the network.
- HTTPS encryption is required for protecting either method during transmission.
- The API documentation determines where the key must go; if a key is exposed, regenerate it immediately.
Key Takeaways
- API keys are primarily transmitted either as URL query parameters or as POST data.
- URL parameters place the key in the URL, while POST data places it in the request body.
- URL parameters are more visible through the address bar, browser history, and server logs.
- Neither location is secure during transmission without HTTPS.
- Always follow the API specification, and prefer POST data when the API permits a choice.