API Keys and Basic Authentication
Vendors require cryptographically signed messages to verify both the source of requests and that they have not been altered in transit.
Why Request Integrity Matters
An API request can contain more than an identity claim. Its parameters can also specify an action, an amount, or the resource being accessed. For many ordinary requests, a vendor mainly needs to know who has the API key. For sensitive operations, the vendor may also need assurance that the request was not changed while traveling to the server. Cryptographically signed messages provide this additional assurance: they help verify both the source of the request and whether the request was altered in transit.
Constructing a Signed Request
A signed request begins with the request message and a shared secret key. The client combines them using a mathematical algorithm to create a signature. The client sends the request and the signature to the vendor. The secret itself is not the item being sent as the signature; instead, both parties use their knowledge of the shared secret to participate in creating or checking the signature. The server independently recomputes the signature from the received request and its copy of the shared secret. If the recomputed result matches the signature sent with the request, the signature supports two conclusions: the request came from someone holding the secret, and the request has not been changed since it was signed.
The Shared Secret
A shared secret is confidential information known by both the client and the server. It is combined with a request message through a mathematical algorithm to create a signature, and the server uses its copy to recompute and verify that signature.
A Changed Transfer Request
Detecting a Modified Amount
A client sends a request to transfer 100 dollars to account 5678. The client signs the request with a secret key. An attacker changes the amount to 10,000 dollars and forwards the changed request with the original signature.
Original signing: The client combines the original transfer request and the secret key using a mathematical algorithm, producing a signature.
Interception: The attacker changes the transfer amount but does not know the secret key.
Server recomputation: The bank verifies the received request by recomputing the signature with the changed message and its copy of the secret key.
Comparison: The changed message produces a result that does not match the original signature.
Decision: The verification fails, so the bank rejects the request and the fraudulent transfer is prevented.
A signature protects the integrity of the signed request because changing the message without the secret key prevents the attacker from producing a matching signature.
What do you think happens?
If an attacker changes a signed transfer from 100 dollars to 10,000 dollars but keeps the original signature, what should the vendor do?
Reveal answer
Answer: Reject the request because the recomputed signature does not match.
The server recomputes the signature from the changed message and its copy of the shared secret. Because the message changed but the original signature did not, verification fails.
API Keys Versus Signed Requests
| Approach | What the server can establish | What it cannot establish from this method alone | Typical use |
|---|---|---|---|
| API key authentication | The request came from someone who has the API key | That the request was not modified in transit | Use cases where identifying the requester is the main concern |
| Cryptographically signed request | The request came from someone holding the shared secret and the request matches the signature | Nothing beyond the assurance provided by the signature process | Sensitive data changes, financial transactions, or protected resources |
When a request contains only an API key, the server knows that whoever sent it possesses that key. However, an attacker could intercept the request, change its parameters, and forward it while leaving the API key present. The server would still accept the request because the key is present. A signed request adds an integrity check: changing the message makes the original signature fail verification.
Choosing the Protection Level
Not every request needs a signature. Simple API key authentication is sufficient in many situations where the main concern is identifying who is making the request. A vendor is more likely to require cryptographic signing when the API modifies sensitive data, performs financial transactions, or provides access to protected resources. In those cases, the vendor wants evidence that the requester is authorized and that the request was not altered in transit.
OAuth is a widely used standard technology for signing requests over the Internet. It belongs in the same request-security discussion because it is a recognized way to support signed Internet requests; the underlying assurance still depends on the credentials and secrets used by the participants being kept confidential.
Mistakes That Weaken Authentication
Treating an API key as proof that the request was not modified.
An API key shows that the sender has the key, but the server cannot verify from the API key alone that the request was unchanged in transit.
Fix:
Use a cryptographically signed request when the vendor needs assurance about both the source and integrity of the request.Sending or exposing the shared secret carelessly.
Anyone who learns the secret can forge signatures and create malicious requests that appear legitimate.
Fix:
Keep the shared secret confidential and protect it as carefully as a password.Assuming every API request must be signed.
The source states that simple API key authentication is sufficient for many use cases.
Fix:
Choose signing when the vendor needs increased assurance, especially for sensitive data, financial transactions, or protected resources.
Check Your Understanding
A vendor offers an API that can either read ordinary information or initiate a financial transaction. Explain which authentication approach is more likely to be required for each operation and what assurance the signed approach adds.
Hints
- Ask whether the main concern is identifying the requester or also detecting changes to the request.
- Consider the source's treatment of financial transactions and protected resources.
- State what the server recomputes and compares when a request is signed.
Evaluating Two API Operations
Classify an ordinary information request and a financial transfer request according to whether simple API key authentication may be sufficient or whether a signed request provides important additional assurance.
Ordinary information request: If the main concern is identifying who is making the request, simple API key authentication may be sufficient.
Financial transfer request: A financial transaction is a situation in which the vendor may require a cryptographically signed message.
Additional assurance: The signature supports verification that the request came from someone holding the shared secret and that the request was not altered in transit.
The appropriate approach depends on the assurance the operation requires, not on a rule that every request must use the same authentication method.
Key Takeaways
- An API key identifies a requester who possesses the key, but it does not by itself prove that request parameters were unchanged in transit.
- A signed request combines the message and a confidential shared secret through a mathematical algorithm to produce a signature.
- The server verifies a signed request by recomputing the signature and comparing it with the received signature.
- A valid signature supports assurance about both the request source and the request's integrity.
- Simple API key authentication may be sufficient for many use cases, while sensitive data changes, financial transactions, and protected resources may require signed requests.
- OAuth is a widely used standard technology for signing requests over the Internet.
Key Takeaways
- API keys show possession of a credential, but they do not by themselves verify that a request was unchanged in transit.
- Signed requests use a shared secret and a mathematical algorithm to create a signature tied to the request message.
- The server recomputes and compares the signature; a changed message causes verification to fail when the attacker cannot create a new valid signature.
- Shared secrets must remain confidential because anyone who learns one can forge signatures.
- Signed requests are especially useful for sensitive data changes, financial transactions, and protected resources, and OAuth is a widely used technology for signing Internet requests.