Shakespeare’s plays are wonderful expressions of beauty and romance. His plays are also complicated, tragic, and hard to understand. Working with OAuth can feel a lot like Shakespeare. It sounds overly complicated, but the more time you spend with it, the more you see the underlying beauty and begin to truly understand it.

Let’s demystify some aspects of OAuth so you, too, can see the beauty and benefits to using it. If you’re already familiar with OAuth, skip ahead to take a look at the basic OAuth setup with Square.

Before we go into explaining OAuth , it’s worth talking about when you should be implementing it. A lot of API’s require utilizing OAuth, but sometimes you might not really need to use it. If you’re building an integration solely for your own use or your own application, you’re probably fine using your personal access token. If you’re wanting to build an application that needs access to multiple accounts or needs granular access, you’ll want to build out an OAuth integration. Even for your own infrastructure, if you have an ETL service, you might want to create an access token specifically for just that service that has read-only access.

Behind the Scenes of OAuth

To explain OAuth, we’ll walk through it like acts in a play. The first act is the authorization, the second act is the redirect, and the third act is acquisition. There’s also a prologue — getting things set up with your authorizer (in this case, Square) to register your application and get all your special credentials to use in the process.

In the first act, we’re sending the user off to the authorization server to ask for some permissions — like a kid who wants to go on a field trip. In order to attend, they’re sent to their parent with a list of what the field trip entails, and the parent has to sign off on it. For OAuth, you’re sending a user to the authorizer with your scope (permissions) that you would like to have. Then the user can see everything being requested and confirm that they would like to grant your application access for those permissions.

The second act is the redirect, which is where Square sends back a code to your application that can be used to acquire an access token. This should seem familiar if you’ve ever used SMS to log in to something. You need to provide both your password and the code that was sent via SMS in order to log in. The code sent back to your application from Square is your authorization code and is used by your application in the final act of getting the access token.

The third act is where we finally receive our access token from Square so we can process API requests for our user. Here, we need to provide the authorization code we received in the redirect to our callback url and our own application secret (which is acquired when registering with Square) in order to get our user’s access token. The access token can then be used to make API calls on behalf of our user.

The Benefits

We’ve gone through a few analogies and it’s clear that this process is a lot more complicated than simply asking a user for their password or making your user go get a special access token for you. The complexity ensures the process is secure — but it also gifts us more flexibility.

If we simply ask a user for their password, and they forget their Square password, then we’ll have to update our system with this new password and our integration would likely break in the interim (also, don’t ever ask for someone’s password). We also give the end users the ability to gracefully revoke access without having to change their password.

In addition, since we specified the scope up front, we only have to give access to whatever was specified. This means the end user can make an informed decision on what’s being granted. When providing a password, you can’t really control what’s being accessed. It’s all or nothing.