Scenario: I design a REST API where authenticated users can hit the API over TLS. I have to use TLS as the data transmitted over the wire is sensitive. I don't need authorization right now, but I don't want to exlude the possibility. I want to use some kind of API Key(/Secret) method. I would prefer to avoid using OAuth. I have two possible solutions. In both cases, the API key (and secret) would be generated by us.

I. Simple API Key

Include an API key in the HTTP header, I can authenticate the client based on that header. The API key is safe, because of TLS. Replay attacks are not possible, guaranteed also by TLS. Very simple to implement by our clients. As far as I understand TLS, the request cannot be tampered (MAC). All security measures are provided by TLS. The client only adds the API Key HTTP header.

II. HMAC signature with an API secret

The request should include a signature, hashed with the secret, timestamp and the hash of the request payload. Now it cannot be tampered or replayed and the secret is not even transmitted over the wire. Safest, but hard to implement on the client side. (writing client libraries is not an option)

Does the first solution pose any threat and provide sufficient security to my clients (and our API), or I should use the more complicated second one? Also, what are the shortcomings of the first one?


If you're using TLS already, I would lean towards using a secret API key in the header. With an API key you can store that encrypted which protects you in the case of a breach. Make sure your application and server aren't logging the secret key in any form and I would push your client to use long, complex keys. These will be handled by systems not people so there shouldn't be heartburn with having them present a long, complicated key with every request.

The hmac signatures are useful if you want to use an unencrypted channel and accept a little bit or risk. In this case the HMAC provides no benefit and would require you to store the secret in plaintext. In this case, I would consider a secret key to be more secure than a signature.

Performance-wise they are going to be similar.

One other note: Since you are TLS you should take care to make sure your example docs and howtos make it clear how to establish that connection correctly and alarm at certificate mismatches and your client SDK should do that by default.

  • I edited my question for clarity. API keys and secrets are generated by me. As I mentioned it, client SDK is not an option. – gmate Jan 5 '15 at 19:07
  • Updated my answer a little but general idea is the same. HMAC doesn't add any value and creates additional risk. – u2702 Jan 5 '15 at 19:22
  • I'd heavily emphasize the last paragraph. Many, many languages fail to provide a collection of CA keys, and expect the developer to do this or reference one provided in the OS. This isn't often well understood, and developers wind up just turning off the cert verification "to get it to work". – Steve Sether Jan 5 '15 at 19:30

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.