Creating a partner API using personal access tokens

Recently, the team working with our client Bromma was tasked with creating a partner API for the service we are developing. In close collaboration with Bromma, we have been building their spreader monitoring system (SMS) which is being used by ports across the globe. A spreader is a machine that moves containers, primarily from cargo ships to shore and vice versa. The system allows ports to better maintain their spreaders, which in turn improves their productivity and creates a safer work environment.

The partner API is an add-on to the service, designed to enable port owners to make use of the data produced by their spreader fleet. This opens up a range of possibilities for the port owner to better manage their operations. In this article we will dive into how we created this API together with Bromma, as well as which considerations we took into account – from security and documentation to access management and monitoring.

API types and how to choose the right type of API for your needs?

APIs – application programming interfaces – allow systems to communicate with each other. This can improve business processes by automating workflows and adding integrations with other systems. Different kinds of APIs exist, the most common ones being private, public and partner APIs.

A private API is an API only accessible within a private cloud environment, such as within a VPC. It is only accessible by the organization that manages it.

A public API is one that is available to the general public. Its purpose is to make it as easy as possible for application developers to make use of the API, and it can be used by anyone. A partner API is one that is available to a partner that has been given access to it, often via a contractual agreement.

This article will look at how we created a partner API. First of all, it's important to understand what value can be derived from an API. Together with one of the port owners, we assessed which data was of interest. After that we started designing how this data would be made accessible through the API.

Since this API is available as an add-on, it's important that only customers that pay for the service have access to it. We do not want to maintain a set of API keys for the users ourselves, since everything should be automated. We found great inspiration from the GitHub API, which lets users manage their own personal access tokens (PATs).

What are personal access tokens (PATs)?

Personal access tokens (PATs) provide a secure way of managing access to an API. They give users the ability to create their own set of tokens, which can be used to access the API, shifting the responsibility of managing the keys to the user. It also makes it easy to track how often the token is used, and to revoke access if the token ends up in the wrong hands. PATs are used by companies such as GitHub, GitLab and Microsoft, to name a few.

Based on our experience, these are the most important things to take into account when creating a partner API using PATs:

Access management

PATs give us the ability to give restricted access to data in our API, so that users can only see data that belongs to them. Users can create several different PATs, each with their own permissions, as this is set by the user. Users can then revoke the access token as they wish.

Security

PATs function similarly to passwords. Once a PAT is created by the user, it receives a unique identifier, which is then stored as an encrypted hash on our servers. In user authentication, the user provides their own password, but with a PAT, a unique identifier is created by the service.

As the user then tries to access the API, they provide their unique identifier to the server, which checks whether the PAT exists and is still valid, and that it has permission to access the requested data. Every request made to the API is logged – this is useful because we want to trace usage patterns in case the PAT is used in a suspicious manner from a security perspective.

GitHub has summarized the benefits of using access tokens instead of passwords as being:

Unique – tokens are specific to GitHub and can be generated per use or per device

Revocable – tokens can can be individually revoked at any time without needing to update unaffected credentials

Limited – tokens can be narrowly scoped to allow only the access necessary for the use case

Random – tokens are not subject to the types of dictionary or brute force attempts that might threaten simpler passwords that you need to remember or enter regularly

It's important to think through the security aspects of the API. PATs must be created in a trusted channel, and in our case, that means using HTTPS when issuing a PAT. The PAT is also made visible to the user only once; after that the only way to see the identifier is to re-generate an identifier for the token.

API documentation standards and best practices

Documentation is very important in order for application developers to easily get started with working on the API. It describes how to use the API and which endpoints are available. An industry standard for API documentation is using the OpenAPI format. It is a programming language agnostic format for describing HTTP APIs. Using it also makes it simple to host your API documentation using tools such as Swagger UI and ReDoc with ease. With Swagger UI, you can provide a testable environment where developers can test the API in their browsers, before starting to use it in their own software integrations.

Stripe is known for having good API documentation, with code examples and easy to follow descriptions of different functionalities. This can be a good source of inspiration when creating documentation.

Monitoring of APIs

Having monitoring in place gives you the ability to see the usage patterns of your API. This is good both from the security perspective as well as for making sure you have provisioned enough resources to handle the load. If the token is suddenly being used in a different part of the world, then the token can be revoked, and the owner can be notified. GitHub also scans the web for exposed tokens, that way they can also revoke tokens and notify token owners in case they have been compromised.

Other considerations on API design

The above lists the most important aspects of using PATs for this purpose, but that’s not all there is to it. There are also other considerations to take into account, such as rate limits, which limit how many requests can be made for your API. Along with monitoring, this comes in handy in making sure your API is capable of handling the load that is being put on it.

Versioning is equally important to take into account, as you will have to think about how to update your API so that existing users can still access it when you make updates. Semantic versioning should help you with this.

Communicating to token owners that their tokens are about to expire – or if a token is revoked for some reason – is a good practice. Additionally, communicating when your API is being updated to a new major release is something to keep in mind.

To summarize, implementing this partner API yielded several important learnings. Using knowledge accumulated from other companies as well as from internal discussions with experienced developers meant we were able to implement a solution that successfully took into account several key factors (including how to manage access to the API in a secure manner using PATs). Additionally, it enabled us to provide a smooth developer experience with documentation that lets users easily read about the different endpoints and test them.

If you’re interested in the Bromma SMS API, you can read more about it here.