API authentication: API keys, basic auth, OAuth 2.0 and JWTs

Authentication vs authorisation

Authentication answers who you are. Authorisation answers what you are allowed to do. An API normally does both on every request: it checks the credential, then checks whether that identity may perform this method on this resource. Remember the status codes: 401 for failed authentication, 403 for failed authorisation.

Simple methods: API keys and basic auth

An API key is a long random string the provider gives you. You send it in a header such as X-API-Key or Authorization. Keys are easy to use but usually do not expire on their own, so a leaked key stays useful to an attacker until someone revokes it.

Basic authentication sends username:password encoded in Base64 in the Authorization header. Base64 is encoding, not encryption; anyone can reverse it (try the Base64 tool). Basic auth is only acceptable over HTTPS, and many platforms now use it just to obtain a token on first login.

export NMS_TOKEN="$(cat ~/.secrets/nms_token)"   # or use a secrets manager
curl -s -H "Authorization: Bearer $NMS_TOKEN" \
     -H "Accept: application/json" \
     https://nms.example.com/api/v1/devices

OAuth 2.0 and its flows

OAuth 2.0 is a framework for issuing access tokens. Instead of sharing a password with every application, an authorisation server issues tokens that are short-lived and limited by scopes such as devices.read. The two flows you will meet most:

• Client credentials: for machine-to-machine work such as an automation script. The script authenticates as itself with a client ID and secret (or a certificate) and receives a token.
• Authorisation code with PKCE (Proof Key for Code Exchange): for apps acting on behalf of a signed-in user. The user logs in at the identity provider, never giving the app their password.

Older flows such as the implicit grant and the resource owner password grant are discouraged in current guidance, including the OAuth 2.0 Security Best Current Practice (RFC 9700). OpenID Connect (OIDC) builds on OAuth 2.0 to add a standard way of proving the user’s identity.

JSON Web Tokens

A JWT (JSON Web Token) is a common format for access tokens. It has three Base64url parts separated by dots: a header (which algorithm), a payload of claims (issuer, subject, audience, expiry, scopes) and a signature. The signature proves the token was issued by a trusted party and has not been changed. It does not hide the contents, so never put secrets in a JWT payload.

An API that accepts JWTs must check: the signature with the expected algorithm and key, the issuer (iss), the audience (aud), and the expiry (exp). Classic mistakes include accepting the none algorithm, letting the token choose its own algorithm, and skipping the audience check.

import jwt   # pip install PyJWT

claims = jwt.decode(
    token,
    key=public_key,
    algorithms=["RS256"],          # fixed list, never from the token
    audience="https://api.example.com",
    issuer="https://login.example.com/",
)

Storing and handling secrets

Tip: if a key ever lands in a Git commit, deleting the file is not enough. Revoke the key at the provider straight away, then clean the history.