Token-Based Authentication
Simple API key authentication can be sufficient when the main concern is identifying who is making the request.
Why a Request Needs More Than a Key
An API key tells a vendor that a request came from someone who possesses that key. In some situations, that identification is enough. But an API key alone does not allow the vendor to determine whether the request was modified while traveling to the server. A cryptographically signed request provides an additional assurance: the request came from the holder of the shared secret and has not been altered since it was signed.
Consider a fund transfer request that asks a bank API to transfer 100 dollars to account 5678. If an attacker changes the amount to 10,000 dollars while forwarding the request, the original signature no longer matches the modified message. Because the attacker does not know the secret key, the attacker cannot create a matching signature, so the bank rejects the modified request.
How Signing Creates Assurance
The client creates a signature by combining the request message with a shared secret key and applying a mathematical algorithm. The client sends the request and its signature to the vendor. The vendor independently recomputes the signature using the request it received and the shared secret. It then compares its result with the signature that accompanied the request.
A matching signature supports two conclusions: the request was produced by someone who holds the shared secret, and the request has not been changed since it was signed. If the message changes but the signature does not, the vendor's recomputed signature will not match.
Detecting an Altered Transfer
A client signs a request to transfer 100 dollars to account 5678. An attacker changes the amount to 10,000 dollars but leaves the original signature attached.
- 1Original signing
The client combines the original transfer request with the shared secret and creates a signature.
- 2Interception
The attacker changes the request amount but does not know the shared secret.
- 3Verification
The bank recomputes the signature from the changed request and the shared secret. The result differs from the original signature.
- 4Decision
Because the signatures do not match, the bank rejects the modified request.
The altered transfer is prevented because the attacker changed the message without being able to create a valid replacement signature.
The Secret Behind the Signature
The shared secret is the critical confidential input to the signing process. Both the client and the vendor must know it so that the client can create a signature and the vendor can recompute it. Someone who learns the secret can forge signatures that appear to come from the client and can create malicious requests that the server accepts as legitimate.
Choosing the Authentication Strength
| Method | What the vendor can establish | When it may be appropriate |
|---|---|---|
| API key | The request came from someone who has the key | Use cases where identifying the requester is the main concern |
| Cryptographically signed request | The request came from the holder of the shared secret and was not altered after signing | Requests that modify sensitive data, perform financial transactions, or access protected resources |
The choice depends on whether the vendor needs only requester identification or also assurance that the request was not modified.
Not every API request needs a cryptographic signature. Simple API key authentication can be sufficient when the main concern is identifying who is making the request. Vendors require signed messages when they need increased assurance about the source and integrity of a request, especially for sensitive data changes, financial transactions, or protected resources.
OAuth in the Larger Picture
OAuth is a widely used standard technology for signing requests over the Internet. In this topic, the important connection is that OAuth belongs to the family of technologies used when requests need signing rather than relying only on a simple API key.
Mistakes That Weaken Authentication
Common mistake Assuming an API key proves that the request was not modified
What it looks likeA request contains a valid API key, but an attacker changes one of its parameters before forwarding it.
Why it failsThe vendor can identify someone who has the key, but the key alone does not verify that the request remained unchanged in transit.
Do this insteadUse a cryptographically signed request when the vendor needs assurance about both source and message integrity.
Common mistake Treating a shared secret as ordinary configuration
What it looks likeA secret is committed to version control or written to application logs.
Why it failsAnyone who learns the secret can forge signatures and create requests the server may accept as legitimate.
Do this insteadKeep the secret confidential and do not commit it, log it, or transmit it over an unencrypted channel.
Common mistake Signing a request without protecting the secret
What it looks likeA client uses a shared secret correctly but sends that secret over an unencrypted channel.
Why it failsThe security of the signed request depends entirely on the secrecy of the shared key.
Do this insteadProtect the shared secret as carefully as a password.
First identify what assurance the vendor needs. If requester identification is the main concern, a simple API key may be sufficient. If the request changes sensitive data, performs a financial transaction, or accesses a protected resource, determine whether the vendor requires a cryptographically signed message.
Check Your Understanding
A vendor receives a request containing an API key. An attacker changed one parameter before forwarding the request. What can the vendor establish from the API key alone, and what additional mechanism would let the vendor detect the alteration?
Hints
- Separate identifying the holder of a credential from verifying the integrity of the message.
- Think about what the vendor recomputes when it receives a signed request.
What do you think happens?
If an attacker changes a signed request but does not know the shared secret, will the original signature still verify?
Reveal answer
No. The vendor's recomputed signature will not match the original signature because the message has changed.
The signature is created from both the request message and the shared secret. Changing the message changes the result that the vendor computes during verification.
Essential Takeaways
- 1A cryptographic signature is created by combining a request with a shared secret using a mathematical algorithm.
- 2The vendor verifies a request by recomputing the signature and comparing it with the signature sent by the client.
- 3A valid signature provides assurance about both the request's source and its integrity after signing.
- 4Shared secrets must remain confidential because anyone who learns one can forge signatures.
- 5Simple API keys may be sufficient for requester identification, while signed requests are important for sensitive, financial, or protected operations.
- 6OAuth is a widely used standard technology for signing requests over the Internet.
At a glance
- Signed requests combine a message with a shared secret to produce a signature.
- The vendor recomputes and compares the signature to detect alteration.
- A signature indicates that the request came from the holder of the secret and was not changed after signing.
- API keys may be enough for identification, but sensitive operations often require signed requests.
- OAuth is a widely used technology for signing requests over the Internet.