Design Considerations

API authentication is far from standardized across the industry. Some APIs use HTTP Basic authentication with a user id and password. Some simply use an API key in the Authorization header. APIs that are called on behalf of the user often use a Bearer token, usually in the form of a JWT sent in the Authorization header. Finally, some APIs use a method to sign the request, using a shared secret.

Authentication protocols that use static values, such as Basic Authentication or only API keys, sent over the wire, run the risk of those credentials being leaked. While it’s unlikely that those credentials would be leaked in a secure TLS connection, it is much more likely that other mechanisms may accidentally contain the plain text version of the credentials. The most common example would be web server logs, but other components may also have these values such as firewalls, proxies, analytic frameworks, and the browsers themselves.

A more secure approach would be to never send the credentials in plain text. In fact, most UI systems when authenticating a user via a user id and password do not send the password to the server. Instead, they send a hash of the password, for this very reason.

We have designed our authentication protocol to provide both flexibility and security, allowing our customers to choose the right level of security for their purposes. The more secure approach includes signing various parts of the request, including a timestamp, to mitigate against the attacks mentioned above. However, for flexibility, we do allow our customers to choose which, if any, parts to sign, with the exception of the API key, which must always be signed.

This latter approach more closely aligns with the methods that send static values for authentication, but ensures that the secret key itself is not sent with the request.