Card 02/ 12
How an API Knows Who Is Calling: Keys, Sessions, Tokens and Certificates
Five methods prove a caller, and four questions tell them apart.
APIs authenticate callers in five common ways: an API key, a session, a bearer token, a JWT, which is one kind of bearer token, and mutual TLS. Four questions tell them apart: what proves the caller, where that proof travels in the request, which kind of client it suits, and how access is cut off when it should end. Every card on a method in this topic answers the same four, in that order.
| Method | What proves the caller | Where it travels | Suits | How access is cut off |
|---|---|---|---|---|
| API key | A long random secret per project | A request header | Server-to-server calls, metering | Revoke the key |
| Session | A random id pointing at state on the server | A cookie | The API's own browser front end | Delete the session |
| Bearer token | A token issued by an authorisation server | Authorization: Bearer | Apps acting for a user | Expiry, or revocation at the issuer |
| JWT | A token whose claims are signed | Authorization: Bearer | Services that verify without a lookup | Expiry, unless extra checks are added |
| Mutual TLS | A client certificate and its private key | The TLS handshake, before any header | Services inside one system | Revoke or stop renewing the certificate |
Not five rivals. Some rows combine. A session id is usually carried in a cookie, so "cookie or session" is not a choice. A JWT is a format a bearer token can take, not a separate way of sending one. Mutual TLS can run underneath a token, proving the machine while the token names the user.
What a caller is. A person, through an app acting for them; a program belonging to a partner; or one of the API's own services. The method follows from which.
The cut-off question is easy to skip. Every method gives access; the difference that matters on a bad day is how fast it can be taken away. A key is revoked at once; a JWT may stay valid until it expires.
So choose a method by answering the four questions for the caller in front of you, not by picking the most familiar one.
← → move through sections and cards