Concepts / Introduction to APIs and Web Services

Introduction to APIs and Web Services

Some APIs require the key in the URL, some require it in POST data, and some accept either.

  • Programming

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?

  • Only in the URL

  • Only in the request body

  • In the URL as a query parameter or in POST data

  • In the API response

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.

API endpointhttps://api.example.com/data?query string beginsapi_keyparameter name=joins name and valueabc123xyzkey value
Where does the API key appear when it is transmitted as a URL parameter?

Following the Key Through a Request

Clientcreates requestURL parameterapi_key=abc123xyzAPI serververifies keyPOST datarequest bodyplaces key in URLplaces key in bodyrequestrequest
How does the API key travel from the client to the API server in each transmission method?

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

URL parameterkey in URLAddress barvisibleRequest bodyhidden from URLHTTPSrequired for either methodBrowser historyvisiblePOST datakey in bodyServer logsvisibleappears inappears inappears inappears inneedsneeds
What parts of an API request can expose the key, and how does that differ between the URL and the request body?
MethodKey locationExposure described in the sourceImportant requirement
URL parameterURL query stringVisible in the address bar, browser history, and server logsUse it when the API specification requires it
POST dataHTTP request bodyHidden from the URL and less likely to be accidentally exposed through browser history, server logs, or shoulder surfingUse it when the API specification allows or requires it

Both methods transmit the key, but they place it in different parts of the request.

Reading the API Specification

API scenariorequest to protected APIAPI documentationrequired key locationURL parameterif specifiedPOST dataif specifiedcheckrequires URLrequires body
Given an API scenario, which method should be used to transmit the key, and what determines that choice?
  1. 1
    Read the API documentation before constructing the request.
  2. 2
    Check whether the documentation requires the key in a URL parameter, in POST data, or accepts either location.
  3. 3
    Place the key exactly where the API specification says it belongs.
  4. 4
    Use HTTPS for the complete connection regardless of which method is required.
  5. 5
    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

Worked example

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.

  1. 1
    URL parameter

    Append a query string to the endpoint: https://api.example.com/data?api_key=abc123xyz. The key is part of the URL.

  2. 2
    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"}.

  3. 3
    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.

  4. 4
    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.

Result

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

  • Common mistake

    Putting the key in the URL when the API requires POST data

    What it looks like

    A request is changed to use ?api_key=abc123xyz even though the documentation requires the key in the request body.

    Why it fails

    The API designer specifies the accepted location. A request that does not follow that specification may not be accepted.

    Do this instead

    Read the documentation and place the key exactly where the API requires it.

  • Common mistake

    Assuming POST data is secure without HTTPS

    What it looks like

    The key is placed in the request body, so the connection is sent without HTTPS.

    Why it fails

    POST data is hidden from the URL but is still transmitted over the network. Neither method is secure without HTTPS encryption.

    Do this instead

    Use HTTPS whenever transmitting an API key.

  • Common mistake

    Sharing a URL that contains an API key

    What it looks like

    A URL containing the key as a query parameter is copied into a message or shared for troubleshooting.

    Why it fails

    URL parameters are visible in the address bar, browser history, and server logs.

    Do this instead

    Do not share URLs or requests that contain an API key.

  • Common mistake

    Leaving an exposed key active

    What it looks like

    A key appears in a shared URL and remains in use.

    Why it fails

    An exposed key may be compromised.

    Do this instead

    Regenerate the key immediately and update applications that use it.

Practice the Decision

EASY

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.
  1. 1
    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.

Related Topics

Related concepts

More concepts starting with I