API key vs JWT - which authentication to use and when

Question

I have read multiple pages/blog posts on API key vs JWT and still I'm confused when to use one of them. Most recent one are saying that JWT became a standard for API authentication but then it became confusing for me in few cases described below.

JWT "no-brainer" choice is for any UI app which will need to authenticate user as well any API calls which require authorization on the API not just authentication.

Then to voice came up APIs which requires only authentication and do not need to identify individual user. JWT in that case looks like an overkill.

On another hand how does it look when JWT is used by API (direct call, no UI) and is not "static" and that will require to generate refresh token for it. How in a general way API should to handle it? Should be that done per each request?

Answer 1

JWT "no-brainer" choice is for any UI app which will need to authenticate user as well any API calls which require authorization on the API not just authentication.

Both API key and JWT can provide authentication and authorization. API key is on project scope and JWT is on user scope.

API keys are considered to be vulnerable to man-in-the-middle attacks, so not as secure as authentication tokens (refer to Google Cloud API key doc).

Example use case for API keys is using Endpoints features such as quotas. Each request must pass in an API key so that Endpoints can identify the project that the client application is associated with.

Example use case for JWT is authentication between Microservices. Refer to this doc for details on use case with more than this two authentication method.

how does it look when JWT is used by API (direct call, no UI) and is not "static" and that will require to generate refresh token for it. How in a general way API should to handle it? Should be that done per each request?

When the client logs in, the authorization server API issues access token and refresh token, and sends them back to client in response. They are both JWT but refresh token is much long-lived compared with access token. The client stores the access token in the HttpOnly cookies. Refresh tokens are usually subject to strict storage requirements to ensure they are not leaked. Until the access token expires, the client uses it to call the API endpoint. When it expires, the client sends the refresh token to the auth-server, and the server issues new access token.

Please refer to this article for more details on refresh tokens.

Note you may not have to store and use refresh token at all.

Answer 2

The debate between API keys and JWT tokens is often mischaracterized as being simply JWT is standardized and more secure. There's much more balance and nuance to the decision.

You only need to look at the best API-first companies in the world like

• Stripe
• Twilio
• AirTable
• SendGrid
• GitHub (for non 'on-behalf-of-user' operations)

... and look at their preferred authentication method (API keys) to realize that API keys can be both secure and offer additional benefits (there's no way Stripe would use API Keys if they weren't considered a secure option).

On security, there are some benefits:

• Users can self-serve and revoke keys
• Revoking leaked JWT tokens or client credentials can be very hard, and will often invalidate everybody's token - not just the leaked credential
• Opaqueness - JWT tokens are parseable by anybody - being able to see the claims might leak information to would be attackers, whereas the an API key is an opaque token
• Tools like GitHub API Key scanning can look for patterns of tokens that are checked-in to source control - this is not supported for JWT today.

What's more API keys have a number of benefits - that's why the best APIs tend to prefer them:

• They're much easier for developer to use
• They're easier to test (single curl command) and
• You can reduce the TTFC (Time to First Call) - a metric most API-first companies

I wrote about this here Wait, you're not using API keys? and talked about it here How the fastest growing companies develop their public API.

Answer 3

API Keys and JWTs embedding authorization are both examples of bearer tokens. The trust lies with the bearer of the token, both of them are subject to exposure and malicious use. Neither pattern is inherently safer than the other, but differ primarily in whether the information they represent is 1) verifiable by an external party and 2) require a call to a central agency to validate.

API Keys are opaque tokens. They are typically used for client-identification, since they are weak authentication and authorization models. You build rate-limiting policies around them, or use them to authorize access to an API at a client-by-client basis. If you need authentication data (a principal ID) or authorization data (scopes of access) you have to fetch them from a central authority.

JWTs can be used in a similar fashion. They also allow more sophisticated models by either signing (JWS) or encrypting a payload (JWE). With a JWS you provide the bearer and recipient crypographic proof that the contents haven't been changed since it was issued. With JWEs you can obfuscate information from external parties while allowing them to validate the token itself. They can be Base64 encoded and used the same as an API key, but if you have large payloads (lots of authorization data) you can exceed header sizes.

Both API Keys and JWTs need to handle revocation. Tokens that are exposed need to be removed from circulation. For API Keys the central host simply says the key isn't valid. For JWS/JWE you use the JTI to provide an invalidation list (similar to OCSP stapling or a cert revocation list).

The choice of which to use depends on your infrastructure, largely. If you're using an API Gateway, most will support an API Key model pretty easily. JWS/JWE models can allow those gateways to not call a central service, which is more performance. If you're building a microservice model, you certainly want to consider JWS/JWE - at least internally - as the app-to-authZ chatter can be very expensive.