api-auth-patterns

API Authentication Patterns

Secure authentication and authorization implementation patterns for APIs, covering OAuth 2.0, JWT, API keys, mTLS, and session management.

Knowledge Base

OAuth 2.0 Flows

Authorization Code with PKCE (Recommended for most applications)

The most secure flow for applications that interact with users. PKCE (Proof Key for Code Exchange, RFC 7636) prevents authorization code interception attacks and is required for public clients and recommended for all clients.

Flow:

1. Client generates random code_verifier (43-128 characters, unreserved URI characters)
2. Client computes code_challenge = BASE64URL(SHA256(code_verifier))
3. Client redirects user to authorization endpoint with code_challenge and code_challenge_method=S256
4. User authenticates and consents
5. Authorization server redirects back with code
6. Client exchanges code + code_verifier at token endpoint
7. Authorization server verifies SHA256(code_verifier) == code_challenge and issues tokens

Security requirements:

• State parameter: Cryptographically random, bound to user session, verified on callback
• Redirect URI: Exact match validation (no wildcards, no path traversal)
• PKCE: S256 method only (plain method provides no security)
• Token endpoint: Authenticated with client_secret (confidential clients) or PKCE only (public clients)

Client Credentials (Machine-to-machine)

For service-to-service communication where no user is involved.

Security requirements:

• Client secrets rotated regularly and stored securely (not in code)
• Scope limited to minimum required permissions
• Short token lifetimes (5-15 minutes)
• mTLS client certificate binding for high-security environments

JWT Best Practices

Token Structure and Signing:

// Header
{
  "alg": "RS256",   // Use asymmetric algorithms for distributed validation
  "typ": "JWT",
  "kid": "key-2024-01"  // Key ID for rotation support
}

// Payload
{
  "iss": "https://auth.example.com",   // Issuer - validate this
  "sub": "user-uuid-here",             // Subject - the user identifier
  "aud": "https://api.example.com",    // Audience - validate this
  "exp": 1700000000,                   // Expiration - short-lived (15-60 min)
  "nbf": 1699999000,                   // Not before
  "iat": 1699999000,                   // Issued at
  "jti": "unique-token-id",            // JWT ID - for revocation tracking
  "scope": "read:users write:orders"   // Scopes/permissions
}