- Upshift
- Posts
- The UX of API Keys
Summary
An API key is associated with one client entity (a user, or an organization).
API keys are common in many platforms today, but each platform has their own UX and ergonomics when it comes to creating and using them.
There are several quality-of-life investments a platform can make to make it easier for their users, like API key self-serve, organization API keys, and more.
Where API access tends to start
When an engineering team sets out to build a public-facing API, they immediately have to come up with some approach to authentication and authorization.
The first path that tends to be considered is using API keys, which is pretty straightforward. A user already has an account, so the engineering team devises a way for the user to, behind the authentication, create an API key, which is usually just a string of characters, for themselves.
If the platform has a concept of “organizations,” which is common in B2B SaaS, the user may also be able to create an organization API key, which is associated with the organization instead of that one user.
Depending on the platform, the user may create the API key in a variety of places. It may happen in a web app they already use for UI workflows, or a command-line interface (CLI). Some platforms even have their users create a support ticket and have the Customer Success team manually provision an API key for the person asking.
These API keys may or may not expire after some time. But, the nice property they have is that once provisioned, they can simply be passed in all API requests, and the platform server can verify that the key is valid and immediately service the request.
Because the user had to be authenticated to create the API key, the key implies authentication. For authorization (which resources can actually be accessed), the platform server needs to inspect the permissions and scopes associated with the key and determine if the request is allowed to be served.
The UX of delegated access with API keys
Continuing with the API key architecture, let’s consider what the user needs to do if there is a third-party app that wants to access resources on their behalf. This is called delegated access, since the user is delegating permissions to the app to access user resources.
The user needs to give the third-party app the API key they have. This means copy-pasting it into the third-party app UI.
This manual flow of the user getting an API key from the platform and middle-person’ing it to the third-party app is not that hard, but it can be error-prone. And imagine if the user wants to give access to many apps. They have to do this copy-paste flow for each app, which is annoying.
Why can’t the third-party app just create its own API key? Because that API key would be associated with the third-party app identity, not the user identity.
To avoid the copy-paste problem, the platform should adopt OAuth 2.0, which is a better and more secure authorization method for delegated access. We’ll talk more about the comparison in the next blog post.
Best-in-class API key UX
There are some nice UX patterns that platforms can adopt to make the quality-of-life for the user better:
API key self-serve - Users should be able to create an API key for themselves instead of having to request and wait for the platform team to manually provision one for them, which may take days.
Organization API keys - When a user can create an API key to represent the organization instead of their particular account, they can share the key with the third-party app or other team members in their organization without needing to worry about giving others personal account access.
API key names - Users should be able to name an API key when it is created, which means they can write down which app or workflow the key is for. This comes in handy with troubleshooting issues down the road.
API key value retrieval - Users should be able to access the API key value after it has been created. This is more work for the platform to support, since they need a secure place to store API keys. But if supported, users can always come back and retrieve a key value again if they forgot it or did not store it themselves.
Expiration controls - Users should be able to set an expiration date for the API key, which means they can pre-plan for a third-party app to lose access after a certain period of time. A user may intentionally set an expiration date to re-evaluate if they want to continue allowing the third-party app to have delegated access.
API key revocation - Users should be able to revoke API keys. They may forget to do revoke keys if they stop using a third-party app, so the platform should generally have its own default expiration as well.
Not using a JWT - This one may be more controversial.
It’s common for platforms to use a JSON web token (JWT) as the value of an API key, which you notice often starts with “ey…” and can be thousands of characters long. The reason a platform may choose to use JWTs is to avoid having to do a permissions lookup on each request, since the JWT string itself contains the permissions.
Looking at it from the user perspective, it’s easier to work with a shorter string that’s ~30 characters instead of thousands of characters. Copy-pasting is cleaner, and double-checking the value is correct is easier.
As a bonus, if the lookup needs to happen anyways, the platform can invest in supporting dynamic permissions, where the permissions associated with an API key can change after its creation.
If you imagine the user has copy-pasted their API key into a third-party app, it’s nice to be able to simply update permissions instead of making a new API key and having to copy-paste again, navigating between the platform and the app’s UIs.
Are there other UX practices that you enjoy or have noticed? Let us know!