←back to thread

Everything I know about good API design

(www.seangoedecke.com)
428 points ahamez | 4 comments | 24 Aug 25 19:10 UTC | HN request time: 0.001s | source
Show context
cyberax ◴[24 Aug 25 21:29 UTC] No.45007982[source]▶
> You should let people use your APIs with a long-lived API key.

Sigh... I wish this were not true. It's a shame that no alternatives have emerged so far.

replies(2): >>45008330 #>>45008372 #
pixelatedindex ◴[24 Aug 25 22:27 UTC] No.45008372[source]▶
To add on, are they talking about access tokens or refresh tokens? It can’t be just one token, because then when it expires you have to update it manually from a portal or go through the same auth process, neither of which is good.

And what time frame is “long-lived”? IME access tokens almost always have a lifetime of one week and refresh tokens anywhere from 6 months to a year.

replies(3): >>45008399 #>>45008522 #>>45008655 #
cyberax ◴[24 Aug 25 22:52 UTC] No.45008522[source]▶
If you're using APIs from third parties, the most typical authentication method is a static key that you stick in the "Authorization" HTTP header.

OAuth flows are not at all common for server-to-server communications.

In my perfect world, I would replace API keys with certificates and use mutual TLS for authentication.

replies(3): >>45008592 #>>45009001 #>>45011031 #
pixelatedindex ◴[25 Aug 25 00:11 UTC] No.45009001[source]▶
IME, OAuth flows are pretty common in S2S communication. Usually these tend to be client credential based flows where you request a token exactly like you said (static key in Authorization), rather than authorized grant flows which requires a login action.
replies(1): >>45009390 #
1. cyberax ◴[25 Aug 25 01:33 UTC] No.45009390[source]▶
Yeah, but then there's not that much difference, is there? You can technically move the generation of the access tokens to a separate secure environment, but this drastically increases the complexity and introduces a lot of interesting failure scenarios.
replies(1): >>45009622 #
2. pixelatedindex ◴[25 Aug 25 02:26 UTC] No.45009622[source]▶
I mean… is adding an OAuth layer in 2025 adding that much complexity? If you’re scripting then there’s usually some package native to the language, if you’re using postman you’ll need to generate your authn URL (or do username/passwords for client ID/secret).

If you have sensitive resources they’ll be blocked behind some authz anyway. An exception I’ve seen is access to a sandbox env, those are easily generated at the press of a button.

replies(1): >>45009736 #
3. cyberax ◴[25 Aug 25 02:49 UTC] No.45009736[source]▶
No, I'm just saying that an OAuth layer isn't really adding much benefit when you either use an API key to obtain the refresh token or the refresh token itself becomes a long-term secret, not much better than an API key.

Some way to break out of the "shared secret" model is needed. Mutual TLS is one way that is at least getting some traction.

replies(1): >>45019736 #
4. JambalayaJimbo ◴[25 Aug 25 22:12 UTC] No.45019736{3}[source]▶
Refresh tokens aren’t necessarily long lived, you can force the client to exchange for another refresh token.