Common API authentication problems

September 11, 2026 · 15 min read

Authentication errors cluster around a handful of patterns: malformed Authorization headers, JWTs that decode but fail verification, and configuration drift between issuers and resource servers. The fix is almost always visible in the token or headers once you know what to look for.

Bearer token format issues

The header must be Authorization: Bearer <token> with a single space after Bearer. Double prefixes (Bearer Bearer), quotes around the token, and trailing newlines from copy-paste cause 401s that look like invalid signatures. Some gateways expect Authorization: Bearer case-sensitively; others normalize - do not rely on lax parsing in clients.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

# Common mistakes:
# Authorization: bearer ...   (wrong casing on strict servers)
# Authorization: Bearer"eyJ..." (missing space)
# Authorization: Basic ...     (wrong scheme)

JWT claim validation failures

Validators reject tokens when iss (issuer), aud (audience), or azp do not match configured values. A token issued for api.staging will fail against production audience checks even with a valid signature. Custom claims like scope or permissions must match what your policy engine expects - decoding the payload is the fastest way to see the mismatch.

Clock skew and expiry

exp is seconds since epoch in UTC. Laptops without NTP sync cause “token expired” immediately after issuance. Allow a small leeway (e.g. 60 seconds) only on validators, not when issuing long-lived tokens. Check nbf (not before) when tokens are rejected at the exact minute of rotation.

Keys and algorithms

Algorithm confusion (alg: none, HS256 with a public key) is a security issue and a debugging nightmare. Ensure kid in the header maps to the correct JWKS entry after rotation. If you recently rotated keys, stale caches on edge nodes can verify with the wrong key until TTL expires.

Debugging checklist

Decode the JWT locally - confirm exp, iss, aud, and alg.
Compare server clock to NTP; fix skew before chasing signature bugs.
Fetch JWKS from the issuer URL in the token docs; verify kid matches.
Replay the same request with curl using the exact header bytes from logs.

FAQ

Why does my JWT work in one service but not another?: Different services often validate different audiences, issuers, or signing keys. Decode the token and compare each service's validation config.
Is a 401 always an expired token?: No. Missing headers, wrong scheme, invalid signature, and claim mismatches all return 401 or 403 depending on framework defaults.
Should I log full JWTs in application logs?: Avoid it. Log jti, sub, and exp for correlation. Full tokens in logs are credential leaks waiting to happen.

Browse all tools