Authentication for Great Apps

Chances are, if you’re building an app you’d like it to be a great app. There are many things that go into making something great, from solving important problems to user experience and more. We believe extensibility is one of those aspects. Users want to their apps to integrate with how they do their work. In order to enable a larger ecosystem around your app, you need authentication–a method for third parties to gain and prove their ability to act on behalf of your user.

When you think about authentication, it’s tempting to think about your own app’s needs. You might have previous technical decisions that point you toward an easy authentication path, for example. However, it’s important to consider your external audiences first: the developers who will write code against your authentication and the users who will navigate your authentication.

Across the 750+ apps that have integrated with Zapier, we’ve seen many types of authentication. While we do our best to support any method an API uses, we’ve found a couple approaches work better than others:

1. OAuth 2.0 (Authorization Code) when accessing user data
2. API Keys when accessing a developer tool

In this post, we’ll go into details about each of these authentication approaches and how best to incorporate them into your app.

OAuth: Great for Accessing User Data

There used to be a time when users routinely shared their credentials with trusted apps. It seems rather quaint–maybe even dangerous–now, but before OAuth came along, sending your password was one of the only ways to let other apps access your data. There were really good reasons to give someone else access, as there still are today. APIs make it possible to move data between services and gain insights not provided by your own app.

Yet, when users share passwords, they are more likely to be stolen. It’s a well known anti-pattern, which is how we ended up with OAuth in the first place.

If your service stores any data on behalf of a user, OAuth is an excellent choice to help them share that data with other apps. The OAuth 2.0 spec describes a developer-friendly approach that also protects users. When considering how third party apps should access user information in your app, you really need a good reason to choose something other than OAuth.

OAuth does even more to maintain security by using authorization scopes. Developers can select granular levels of access and, in some cases, users are able to make the scope selection themselves.

For example, scopes can restrict access to certain resources, provide read-only access, or give write access to certain areas. The developer accessing an OAuth-based API will request a specific scope, which the user must approve. In some situations, such as GitHub, the user can get more granular, such as disallowing specific repositories.

A final and important reason to use OAuth is that users can revoke access from an app at any time. They do not need to visit the app that is accessing their data to shut it off. Rather, they can go to a dashboard using the service where their data is being accessed.

Users may be surprised how many apps they’ve authorized for popular login and social apps. By revoking an app’s access, any subsequent API calls will be refused until the app sends a valid token. OAuth providers may also choose to revoke tokens for suspicious apps or in the case of known vulnerabilities.

Our Recommended OAuth Flow

Using OAuth makes so much sense for all parties, yet it can still become a developer headache. The OAuth 2.0 spec describes many different approaches, so we’ve documented the flow we most easily support in the Zapier Developer Platform, though we can flexibly handle many permutations (still, you wouldn’t want to be an OAuth Butt).

If you’re familiar with the GitHub or Facebook APIs, you’ll recognize our recommended OAuth 2.0 approach, the authorization_code flow. Here are the steps needed to authenticate a user:

1. Open a new browser window to the OAuth-supported app with the client_id
2. In the new window, the user agrees to share data with the third party app
3. The OAuth-supported app redirects back to the third party app with an authorization_code
4. The third-party app uses the authorization code to retrieve an access token by using the client secret and authorization code.

Some OAuth-supported apps use refresh tokens in addition to access tokens. In those cases, access tokens expire after a short time and refresh tokens must be used to retrieve a new access token.

For a more detailed look at this OAuth flow, along with specific examples, see our OAuth 2 documentation.

API Keys: Great for Developer Tools

Another common way to access an API is through a static API key. It’s a bit like an OAuth token without the entire handshake needed to retrieve it. There are significant security and user experience downsides, but there are still situations where API keys make sense.

Developer tools that solve specific problems are a great use case for API keys. For example, Twilio sends text messages, and Full Contact looks up details of an email address. These types of applications are unlikely to need to access a user’s data. Further, as developer tools, the emphasis is on the developer experience, rather than the end user experience. In most cases, an end user won’t be the one using an API key.

Of course, API keys are used for many apps where end users end up copying and pasting the key to enable a third-party app to access their data. While this is better than using a password, it shares some of those downsides, especially if there is only a single API key for a user’s account. And, since most API keys don’t have scopes, so in that single API situation, it is essentially a password.

Some ways to improve your API key security:

• At a minimum, ensure API keys can be regenerated, effectively revoking access for the previous key
• Provide a mechanism for the user to create multiple API keys, which provides the ability to revoke one app without revoking all
• Allow API Keys to be restricted to read-only, write-only, or read-write when generating

Some of those API key improvements may remind you of OAuth. Certainly, the lessons that led to OAuth came from problems or lack of control from earlier methods. Still, there is a place for these more advanced API keys.

---

OAuth and API keys are not mutually exclusive. GitHub, for example, uses both in different ways. Its OAuth support allows for third-party applications to request access on behalf of users.

GitHub's personal access tokens allow developers to create their own scoped API keys on the fly, an easier way to get started fast with homegrown developer tools.

Next Steps With Your Great Authentication

Now that your app is authenticated, what beautiful things can we build together? It’s important to think back to those two audiences we mentioned at the beginning.

1. Users: help them connect to 750+ other apps they use by integrating your great app into the Zapier Developer Platform.
2. Developers: you’ll need to make sure they know how to use your app’s API. Check out these great documentation examples to get some ideas.

Other ideas or comments? Reach out on Twitter or leave a comment and let us know!