API Authentication Patterns

Also Known As

TL;DR

Explanation

API authentication options: Bearer token (Authorization: Bearer jwt) — stateless JWT, validate signature/expiry/issuer; use short expiry (15min) + refresh tokens. API key (X-API-Key header) — hash stored server-side, scope keys to minimum required permissions, rate-limit per key. Basic auth — only with HTTPS, legacy use only. OAuth 2.0 client credentials — for third-party apps accessing your API on their own behalf. mTLS (mutual TLS) — both client and server present certificates, no passwords, ideal for internal microservices. HMAC request signing (AWS Signature v4 style) — signs request body and headers, prevents replay attacks.

Common Misconception

Why It Matters

Common Mistakes

• Long-lived JWT tokens without revocation — a leaked token remains valid until expiry
• API keys in URL query parameters — logged by servers, CDNs, browser history, and proxies
• No token scoping — one token with full access means any leak is a full compromise
• JWT without signature validation — accepting unsigned tokens with alg:none

Avoid When

• Using API keys in URLs — they appear in server logs, browser history, and referrer headers.
• Long-lived tokens with no expiry or rotation — a stolen token is valid forever.
• Storing API keys in client-side JavaScript — they are visible to anyone who views source.
• Using HTTP Basic Auth over plain HTTP — credentials are sent in every request, base64-encoded but not encrypted.

When To Use

• API keys for server-to-server calls where the key can be stored securely in environment variables.
• OAuth 2.0 + PKCE for user-delegated access — never embed client secrets in mobile or SPA clients.
• JWT bearer tokens for stateless APIs where the token carries claims without server-side session lookup.
• mTLS for high-trust service-to-service communication in zero-trust network environments.

Code Examples

// Long-lived JWT — leaked token valid for 1 year:
$token = JWT::encode([
    'sub' => $userId,
    'exp' => time() + 31536000, // 1 year expiry!
], $secretKey);
// Leaked token: full access for up to 1 year

// API key in URL — logged everywhere:
GET /api/data?api_key=sk_live_abc123

// Short-lived access token + refresh token:
$access  = JWT::encode(['sub'=>$userId,'exp'=>time()+900], $key);  // 15 min
$refresh = JWT::encode(['sub'=>$userId,'exp'=>time()+2592000], $refreshKey); // 30 days
// Leaked access token: valid at most 15 min
// Refresh tokens: stored and rotatable

// API key in header — not logged by default:
// Authorization: Bearer $access
// OR: X-API-Key: sk_live_abc123

References

• ↗ https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html

Tags

Related Terms