How Stitch API security protocols are like a modern hotel

Stitch CTO Natalie Cuthbert breaks down the security protocols of the Stitch API, comparing them to the security of a modern hotel.

Those who still remember the days of frequent business travel will recall the vital role stress-free accommodation plays in enabling a successful trip. The best hotel experience involves a combination of easy access, a smooth check-in process and high levels of security.

Imagine you’re on the road again and checking into a new hotel. In order to safeguard its guests and keep out unwanted visitors, the hotel has certain protections in place. For instance, they will ask guests for their identification when checking in. They’ll also require a reservation against which they can check their ID. Guests are also provided with an electronic keycard during check-in that must be used to enter their rooms.

Much like hotels, most APIs need a way of protecting themselves from unwanted visitors or potential attackers. At Stitch, we work with bank accounts and other sensitive user data, so we have a number of safety and security protocols in place that prevent unwanted individuals from gaining access or stealing information.

One such system is Stitch Single Sign-On – our identity server.

How Stitch’s identity server acts like a hotel

The term “auth” is often used in the security space to refer to two overlapping concepts:

Authentication:

Authentication is about verifying that a user is the individual they say they are. For example, when attempting to check into the hotel, the concierge will ask you for identification and will check your ID against the name on their reservation list. They would know based on the photo on your ID whether the face matches your face, and whether the name and ID number match the ones on their list.

In the context of Stitch, you can think of a user logging into their bank account as someone presenting their identification when trying to check in. If they know their online banking password and can pass a multi-factor authentication check, we have a high degree of confidence that the user is indeed who they say they are.

Similarly, we also ask our clients to provide bank account details to verify whether they exist or not. In this case the client themselves rather than the end user has to prove their identity.

Authorization:

In the context of the hotel, the keycard you receive grants you access only to your floor and your own room. Other guests have different keycards that admit them to the other floors, but you will be unable to enter those floors unless you are given the correct keycard.

Similarly, authorization specifies what a user or client is allowed to do once they have proven their identity. This is frequently performed using a permission system. When a user signs in through Stitch, they give clients permission to access specific features in their account. For instance, if they consent to allowing their transactional data to be read. The client will only be able to access that data if the user has granted them permission.

These two ingredients – authentication and authorization – work hand-in-hand to allow us to secure our APIs while simultaneously protecting both our customers and their users.

Access tokens vs keycards

Stitch Single Sign-On (SSO) uses an authorization protocol called OAuth 2.0. This is often used when you sign into an app via popular internet logins such as Google, Facebook, and Twitter. We also use a standard called OpenID Connect, which adds the authentication layer, providing a uniform mechanism to verify a user’s identity.

When a user signs in and is verified, clients receive something called an access token, which enables them to access the API. The token corresponds only to that particular session.

In the case of the hotel, an access token can be compared to the keycard. Imagine, however, that keycard is only valid for a particular window in time (this is one hour in Stitch’s case, but imagine it’s one night). If you’re looking to stay for a while, that won’t be enough. So when your keycard expires, you need to call the concierge and ask for another one that’s valid for a longer period of time.

For Stitch, an access token gives you access to our API on a time-limited basis. For some use cases, clients might need access to a particular user’s data for days or weeks at a time. In these cases, we also provide something called a refresh token. Clients can use their refresh token to receive another access token and refresh token.

Deeper protection

Now imagine that every guest in the hotel is given their own unique keycard linked to their ID. This would allow the concierge to invalidate a keycard if it’s reported missing, or if the customer misbehaves.

However, there is a flaw with this scheme in that if the keycard is lost or stolen, a miscreant can use it to gain access to the hotel. To solve this problem, the concierge devised a scheme in which, in addition to scanning the keycard, guests must enter a pin code on a keypad installed on their door. This pin is unique to each guest and changes daily. Guests receive their new pin code each morning of their stay.

Similarly, Stitch gives each of our clients a certificate that allows them to generate an unguessable, short-lived code. All privileged interactions with our identity server validate this code, ensuring that server-to-server communication is secured without risk of attack from unwanted third parties.

All these measures to secure the hotel mean that its guests can enjoy their stay in peace, knowing that unwanted intruders are stopped at the door.