We are working on a new API here at SmartFile. The API will act as another method for users to interact with our system. We want to treat it as just another supported protocol.
That said, our initial versions of the API performed authentication utilizing the username and password of the user. The same one used to access the system over various other protocols. I committed code yesterday that changes all of that. It introduces a new form on our API that generates an API key and password for the user. This basically gives the user two username/password pairs for their account.
One of our other developers asked me to justify why this was necessary and I had a little trouble at first. The only reason I could come up with was “This is how it is usually done.” But that is never a good reason to do something.
I did a little research to try and uncover some of the reasons why the other major APIs out there use an API key instead of a user’s authentication credentials. I could not come up with any justification. So as a contribution to other developers in this situation, I will provide below some concrete reasons why this method is superior.
1. Decoupling.
By decoupling the API credentials from the user’s credentials, either can be changed independantly. There are numerous reasons to change credentials frequently, however the more difficult this process is, the less often it is undertaken. If the same credentials are used in applications consuming the API and also by the user for various other reasons, this complicates matters. By using a separate API key, the user can continue to change their password frequently without impacting applications consuming the SmartFile API.
2. Forced Complexity.
In my last post I mentioned that passwords in our system are controlled by our users. This gives our users ultimate control of the level of security they wish to apply to their data. Security is always a trade-off against usability. However, an API is a fairly narrow use-case, the credentials will be configured somewhere and don’t need to be remembered by anyone. In this case, using strong credentials in the form of a complex API key and password has no bearing on usability.
3. Limited Disclosure.
An API key might be disclosed to 3rd parties. Other developers on a team, server administrators or colleagues of another sort may all have occasion to catch a glimpse of the API key. Like it or not, a lot of users use the same password for many systems. If the API credentials are a user’s chosen credentials, then exposing them poses risk.
Above are what I think are the most compelling reasons to choose an API key instead of user selected credentials when developing an API. Of course every coin has two sides and this issue is no different.
1. Complexity.
The use of an API key introduces a level of complexity to the API registration process. It is one more step for a user to perform.
I hope that the above information helps other API developers make an informed decision when choosing their API authentication method. Doing what everybody else does is fine as long as you understand the risks and rewards of doing so.
Please use the comments to inform me of additional facets of this issue, as well as to correct any glaring errors in logic I may have espoused.