API Design: Deciphering Security
Our previous discussions about API design, which are covered in Web API Design, centered on URL design and we hinted about versioning, errors, and client considerations. Recently, we also outlined an API modeling strategy that’s easy to use. Now we’ll discuss the security measures that you can use to surround your API.
Why API security is an important element of API design
As enterprises adjust to the reality of business beyond their core and legacy systems, to millions of mobile devices and social networks at the edge of the enterprise, and new distribution channels like apps (often built by third party or partner developers), the question of end user privacy is increasingly important. As the app economy matures, its participants must move quickly to establish standards that address end-user privacy.
With this in mind, let’s take a look at how three large enterprises handle some of their API security challenges.
Twitter Streaming API v1.0
Authorization: Basic aWhlYXJ0OmFwaXM=
Twitter’s first version of their streaming API uses HTTP basic authentication, which is essentially username and password Base64 encoded (meaning it’s not encrypted).
Amazon Web Services API
Authorization: AWS AKIAIOSFODNN7EXAMPLE:frJIUNo//yllqDzg=
Amazon uses their proprietary scheme for Amazon Web Services (AWS) authorization. This API design pre-dates the OAuth 1.0 specification.
Authorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg
Google uses OAuth, specifically OAuth2 and Bearer tokens.
OAuth is the standout standard
Using OAuth means that apps and APIs don’t have to share passwords to communicate with each other. OAuth2 allows developers to build clients that couple with resources located on other services, like Facebook, Google, and GitHub. Therefore, we recommend OAuth2. Because it’s a standard, there are lots of resources to help you build an OAuth2 security protocol. Another good alternative is using OAuth 1.0a. LinkedIn uses OAuth 1.0a for authorizing clients in their API. HTTP basic has security limits and creating your own API security protocol can be a hassle.
Overall, OAuth eliminates the need to store a password on a mobile device, which adds a layer of security when an API is used by mobile apps built by untrusted developers for a public API. Also, an OAuth token is hard to guess, it is tied to a particular app and user, and it can be revoked without affecting other users and apps. OAuth allows the API provider to revoke tokens for an individual user or for an entire app without requiring the user to change their original password. This is critical if a mobile device is compromised or if a rogue app is discovered.
For more on OAuth, check out blog posts by our colleague Greg Brail: