Best Practices for handling API Clients
We recently re-designed our API Client UI from scratch. In this post, I want to share best practices on handling Access Secrets, and how these influenced our new design.
Each service has its own API Client
Every micro-service, every frontend, every developer, and whoever else directly accesses your API should get its own API Client. This allows request correlation, and to revoke an API Client quickly when you find out it has been leaked. But most importantly, it is the basis for the principle of least privilege:
Each service has the minimal set of permissions to perform its function
For example, a micro-service importing products must not be able to read order data. Should this service be hacked and the API Client stolen, your customer data is still secure.
Remove unused API Clients
For whatever reason an API Client isn’t being used anymore (e.g. a developer leaves the company, a micro-service is replaced with a newer version), you should remove it. If it falls into the wrong hands, no harm can be done anymore.
Rotate API Clients — regularly
You should rotate API Clients on special events, e.g. when a DevOps who handled API Clients leaves your company. But it’s even better if you also rotate them on a fixed schedule. Should an API Client leak, you at least limit the timeframe that it can be used.
How these best practices influenced our new design
Truth to be told, our old UI was not optimized for security. Instead, it was focused on lowering the friction for new developers. As an unknown startup at the time, we had to convince them that our product was worth using, and losing them while setting up an API Client was a no-go.
Therefore, an API Client with full permissions was setup with each project. A developer could just copy it, and get going. While that was great for onboarding, we found that this default API Client discouraged users from creating new clients, or clients with limited permissions.
The biggest change that we’ve done is that API Client secrets are one-time-view only! Everyone has to create their own client, and we don’t select full permissions by default anymore. While the new UX means a bit more work, it strongly encourages two best practices I’ve shared: An API Client per service, and minimal permissions.
But we’ve tried to make up for it! We have a few permission-templates ready, and it is now possible to download the API Client in multiple formats. Instead of having to copy-paste multiple values (e.g. the project key, client id and client secret) into a configuration, you can simply download the full configuration. This is available for all of our SDKs, cURL, bash and Postman. The total time spent setting up a SDK has probably decreased.
API Clients now also show the last time they’ve been used, making it easier to spot and remove unused ones. To assist with regularly rotating API Clients, we show the age of each client, and offer a convenient duplication button.
What a cross-team effort!
Changing the API Clients UI may seem like a small thing — but it actually involved participation from nearly every team within the commercetools product organization! We had to change every tutorial, be it on our main website, in a GitHub Readme, or on a training slide. We worked with every SDK to have their configuration ready to be downloaded. We had to change our authentication service to be able to display the last time an API Client has been used. Our UX Designer had to do a deep-dive into OpsSec and Developer setups. Last but not least, we had to implement the UI itself! Thanks a lot to everyone involved.
Our API Clients UI is a great case study how far along our product has come. We’ve moved on from an early-stage startup to an established product used by large enterprises. Our new UI is prioritizing security above everything else — but we still care about developers like on day one.
