The Developer-Friendly Way to Change Your API Auth

During the lengthy history of public-facing APIs on the Internet, the process of requiring a user's authorization has progressed through a variety of methods. It's great when an API provider supports a newer (and hopefully better) authorization method, but deprecating the older method sometimes leaves the existing users and integrations in a difficult situation. Moving from using API Keys to authenticate users to OAuth v2, for example, is not without its challenges. Here are the ways you can make this valuable process easier and avoid the most common pitfalls when changing authentication methods.

Brief history of authentication and authorization methods

Initially, there was Basic Authentication, which meant the API client possessed a person's username and password, and allowed that software act as the actual person with all of their granted privileges.

This had (and still has) a number of drawbacks, such as the challenge for the client software or site to securely store those credentials—and stay abreast of security best practices and changes, or, if the user changed their password, then all connected integrations with those credentials would stop working.

Eventually, newer methods like API Keys were introduced, so that users wouldn't have to give away their passwords. Some implementations allowed people to generate an individual key for each integration (which could be revoked without affecting their other integrations) or possibly select which privileges the API Key would be able to perform. But the process of generating an API Key was cumbersome, since users had to copy/paste a long string of text from one site into another.

These days, the most commonly used authorization method is OAuth v2. It provides an easy process for people to use when granting permission to an app or website (no more copying and pasting of API Keys!). This allows integrations to provide support for fine-grained permissions (called scopes). Plus, you can set up the option to require a user's access token be discarded and refreshed after some period of time—increasing your security.

The biggest challenge of deploying a newer authorization method? You need to make sure that API clients have a clear path for migrating users' existing records to the newer format, by providing a special authorization migration endpoint which performs the conversion.

Authentication versus Authorization

Before we go proceed, it's worth noting the difference between "authentication" and "authorization".

Authentication proves that you are "who you say you are", like username/password, biometric/fingerprint scanner, photo identification (in real life), or other means.

Authorization is the approval to act on your behalf, like a security badge, or a physical key. Usually, these tangible forms of authorization are granted after performing some kind of authentication/verification of the person. On the internet, that "security badge" is an API Key or access token, which corresponds to your account on a website.

Auth migration considerations

Early versions of APIs generally granted "read/write access for everything". If an integration had a user's authorization, then the integration had "full control" over everything in that user's account—and that required a high amount of trust.

When you deploy a newer version of an authorization type (like switching to OAuth v2), don't expect that users will go through the process of reconnecting all of their existing integrations. The user already granted permission for that integration to act on their behalf (possibly long ago), so asking users to re-authenticate is a cumbersome and redundant step.

Instead, your API should provide an auth migration endpoint, which allows existing integrations to pass in the older auth and receive a newer auth. Check out a few of the "Real World" examples of this a bit later in this article.

Protip: Developers may call your auth migration endpoint multiple times with the same API key. When that occurs, try to return the user's existing OAuth refresh token, along with a fresh access token. This will help reduce the chances of generating excessive quantities (and redundant) refresh tokens for your users.

Watch out for these auth migration pitfalls

If you own an integration that needs to switch users to a newer auth type, there are a few pitfalls to keep in mind when migrating users to a newer authentication type:

• Review Process: Some API providers require you complete a review process, before your OAuth client can be used by "all users." You will need to ensure that your integration is compliant with the updated rules and regulations, so that users can continue using the integration. For example: Dropbox Production Approval guidelines.

• Watch for Client ID bindings: Sometimes, a user's OAuth access/refresh tokens are bound to a specific OAuth Client ID, which makes it impossible to share an authentication between different integrations. Originally, API Keys could be used across multiple/different integrations, but some implementations of OAuth will prevent that, and thus require that each integration must obtain its own access/refresh token.

How to deprecate support for older authorization methods

Eventually, an API provider may decide to no longer accept older authorization methods (like API Keys, which may have "all access" to the data within the user's account). See the helpful tips in our API Geriatrics post, which describes the best practices for shutting off access.

If you are the API provider, avoid scheduling the final deprecation date to occur at "the end of the year", since the API consumers/users may be unavailable to handle any unexpected situations. A better "final date" is something around Groundhog's Day (February 2), so that more people are available to help resolve any issues.

Real world examples

Looking for inspiration or ideas when building an auth migration endpoint? Here are some examples of sites that have successfully enabled the transition to OAuth v2:

• Asana endpoint to exchange API Key to OAuth v2 token
• Dropbox endpoint to convert OAuth v1 token to OAuth v2
• Vimeo endpoint to convert OAuth v1 token to OAuth v2
• Todoist endpoint to migrate personal access token to OAuth v2

---

Upgrading your API to use a newer authorization scheme (like OAuth v2) is a great plan, but make sure you provide a migration path, so that all of the existing integrations can continue to provide a disruption-free path for your users who have already authorized those integrations to act on their behalf.

OAuth v2 APIs are also a great fit with the Zapier Developer Platform, which makes the use cases within your API available without writing code.