Forem: Shoumik Chakravarty

Microservices Patterns

Shoumik Chakravarty — Tue, 26 May 2026 03:07:00 +0000

Microservices Patterns: A Practical Guide to Choosing the Right Architecture

Most teams don't fail at microservices because the pattern is wrong. They fail because they adopted all the patterns at once, before they understood which problems each one was actually solving.

I've watched teams ship a service mesh, an event bus, a saga orchestrator, and a CQRS read model in the same quarter — for a system that had fewer services and limited users. The result is what's now called a distributed monolith: all the operational complexity of microservices with none of the independent deployability or scalability.

This guide walks through the patterns that matter, what each one is actually for, and when not to use it. Code examples are in Python, with a decision matrix at the end so you can match the pattern to your problem.

Microservices vs. Distributed Monolith

A real microservice has three properties:

Independently deployable. You can ship Service A without coordinating with the teams behind Services B, C, and D.
Owns its data. No other service reads or writes its database directly. The only way in is through its API.
Loosely coupled. A change to one service's internal schema doesn't break others.

If you can't deploy a service without redeploying three others, you don't have microservices — you have a monolith with network latency. That's almost always worse than the monolith you started with. Keep this test in mind as we go through each pattern: does this pattern preserve those three properties, or quietly erode them?

1. API Gateway

How it works

An API gateway is a single entry point that sits in front of your services and handles cross-cutting concerns: routing, authentication, rate limiting, request/response transformation, and aggregation.

# Simplified gateway routing logic
from fastapi import FastAPI, Request, HTTPException
import httpx

app = FastAPI()

SERVICE_ROUTES = {
    "/users":   "http://user-service:8000",
    "/orders":  "http://order-service:8000",
    "/payments": "http://payment-service:8000",
}

@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def gateway(path: str, request: Request):
    # 1. Authenticate once at the edge
    if not verify_jwt(request.headers.get("Authorization", "")):
        raise HTTPException(401, "Invalid token")

    # 2. Route to the right downstream service
    prefix = "/" + path.split("/")[0]
    upstream = SERVICE_ROUTES.get(prefix)
    if not upstream:
        raise HTTPException(404, "Unknown route")

    # 3. Proxy the request
    async with httpx.AsyncClient() as client:
        response = await client.request(
            request.method,
            f"{upstream}/{path}",
            content=await request.body(),
            headers={k: v for k, v in request.headers.items() if k != "host"},
        )
    return response.json()

When to use it

Use a gateway as soon as you have more than two or three services that share clients. It centralizes auth, TLS termination, and rate limiting so each service doesn't reimplement them. The example above is illustrative — for production you'll pick between two deployment models.

Serverless vs. server-based gateway

There are two practical ways to run a gateway, and the choice has bigger operational implications than the choice of vendor.

Serverless gateway (AWS API Gateway, Azure API Management consumption tier, Google Cloud API Gateway, Cloudflare Workers). The cloud provider runs the gateway, you describe routes and policies declaratively, and you pay per request. There are no servers to patch, no capacity to size, and it scales from zero to bursty traffic without you tuning anything. The downsides: per-request pricing gets expensive at high sustained throughput, cold starts add latency on the first request after idle, you're locked into the provider's auth/transform model, and customizing behavior beyond what the console exposes usually means writing Lambda authorizers or Workers — which is its own operational surface. Reach for this when traffic is spiky or modest, when your team is small, or when you're already deep in one cloud and want the integration.

Server-based gateway (Kong, Envoy, Traefik, NGINX, HAProxy, Spring Cloud Gateway, EC Instances). You run the gateway as long-lived processes — usually as pods in Kubernetes or instances behind a load balancer. You get full control over plugins, request transformation, and observability, predictable cost at sustained scale (you're paying for capacity, not per request), and you can run the same gateway in any environment, including on-prem. The cost is real: you own patching, capacity planning, HA topology, and config rollout. Reach for this when you have sustained high traffic, complex routing or transformation needs, multi-cloud or hybrid requirements, or an existing platform team that already operates similar infrastructure.

# Kong declarative config example — server-based gateway
_format_version: "3.0"
services:
  - name: order-service
    url: http://order-service.default.svc.cluster.local:8000
    routes:
      - name: orders
        paths: ["/orders"]
    plugins:
      - name: jwt
      - name: rate-limiting
        config:
          minute: 100

A rough rule of thumb: under a few hundred requests per second with unpredictable traffic, the serverless model usually wins on total cost of ownership. Above that, with steady load, the server-based model wins on per-request cost and control. Whichever you pick, treat the gateway config as code — version it, review it, and deploy it through a pipeline.

Tradeoffs

The gateway is a single point of failure and a deployment bottleneck regardless of which model you choose. Every team that needs a new route has to coordinate with whoever owns the gateway config. Keep the gateway dumb — routing, auth, rate limiting — and push business logic into the services themselves. The moment you find yourself writing if-statements about specific user IDs in the gateway, you've made it part of your application.

2. Service Discovery

How it works

In a microservices system, service instances come and go — autoscaling spins them up, deployments roll them, failures kill them. Hardcoding http://order-service-prod-3:8000 won't survive the first deploy. Service discovery solves this with a registry: services register themselves on startup, and clients ask the registry "where is the order service right now?"

import httpx
import random

class ServiceRegistry:
    """Client-side discovery against Consul, etcd, or Kubernetes DNS."""

    def __init__(self, registry_url: str):
        self.registry_url = registry_url
        self._cache: dict[str, list[str]] = {}

    async def resolve(self, service_name: str) -> str:
        if service_name not in self._cache:
            async with httpx.AsyncClient() as client:
                resp = await client.get(f"{self.registry_url}/v1/services/{service_name}")
                self._cache[service_name] = resp.json()["instances"]
        # Simple client-side load balancing
        return random.choice(self._cache[service_name])

# In practice, refresh the cache periodically and remove failed instances

When to use it

You need service discovery the moment you have more than one instance of any service, or as soon as you're deploying to a dynamic environment (Kubernetes, ECS, Nomad). If you're on Kubernetes you get this for free — DNS resolves order-service.default.svc.cluster.local to a healthy pod. Don't build your own unless you have a reason.

Tradeoffs

Client-side discovery (each service queries the registry) reduces a network hop but spreads discovery logic everywhere. Server-side discovery (a load balancer fronts each service) is simpler for clients but adds a hop and another component to operate. On Kubernetes, the platform handles this — don't fight it.

3. Circuit Breaker

How it works

When a downstream service starts failing, the worst thing your service can do is keep hammering it with retries. You exhaust your own threads, queue up requests that will never succeed, and the failure cascades upstream until your whole system is down.

A circuit breaker watches the failure rate of calls to a downstream service. When failures cross a threshold, it "opens" — for a cooldown period, calls fail fast without ever hitting the downstream. After the cooldown, it lets a small number of test requests through; if they succeed, it closes again.

import time
from enum import Enum

class State(Enum):
    CLOSED = "closed"      # Normal operation
    OPEN = "open"          # Failing fast
    HALF_OPEN = "half_open"  # Testing recovery

class CircuitBreaker:
    def __init__(self, failure_threshold: int = 5, recovery_timeout: int = 30):
        self.failure_threshold = failure_threshold
        self.recovery_timeout = recovery_timeout
        self.failure_count = 0
        self.last_failure_time = 0.0
        self.state = State.CLOSED

    def call(self, func, *args, **kwargs):
        if self.state == State.OPEN:
            if time.time() - self.last_failure_time > self.recovery_timeout:
                self.state = State.HALF_OPEN
            else:
                raise RuntimeError("Circuit breaker is OPEN — failing fast")

        try:
            result = func(*args, **kwargs)
            self._on_success()
            return result
        except Exception:
            self._on_failure()
            raise

    def _on_success(self):
        self.failure_count = 0
        self.state = State.CLOSED

    def _on_failure(self):
        self.failure_count += 1
        self.last_failure_time = time.time()
        if self.failure_count >= self.failure_threshold:
            self.state = State.OPEN

When to use it

Use a circuit breaker around any synchronous call to a service you don't control fully — third-party APIs, services owned by another team, anything where a slow response from them shouldn't take you down. Pair it with timeouts (always set timeouts on outbound calls) and bulkheads (limit how many threads any one downstream can consume).

Tradeoffs

A circuit breaker shifts the failure from "slow timeout" to "fast error." That's almost always the right tradeoff, but your callers now need to handle the fast-fail case — usually with a fallback (cached data, a default response, a queued retry). Libraries like resilience4j, Polly, or Hystrix (now in maintenance mode — use resilience4j) implement this properly with metrics built in.

4. Saga — Distributed Transactions Without Distributed Locks

How it works

You can't run a SQL transaction across two services without distributed locks, and you don't want distributed locks. A saga replaces the ACID transaction with a sequence of local transactions, each of which has a defined compensating action that undoes it.

For example, booking a trip might be: reserve hotel → charge card → book flight. If the flight booking fails, the saga runs compensations in reverse: refund the card, release the hotel.

from dataclasses import dataclass
from typing import Callable

@dataclass
class SagaStep:
    name: str
    action: Callable
    compensation: Callable

class Saga:
    def __init__(self, steps: list[SagaStep]):
        self.steps = steps

    def execute(self, context: dict):
        completed = []
        try:
            for step in self.steps:
                result = step.action(context)
                completed.append((step, result))
        except Exception as e:
            # Run compensations in reverse order
            for step, result in reversed(completed):
                try:
                    step.compensation(context, result)
                except Exception as comp_err:
                    # Compensations should be idempotent and logged loudly
                    log.error(f"Compensation {step.name} failed: {comp_err}")
            raise e

# Usage
saga = Saga([
    SagaStep("reserve_hotel", reserve_hotel, release_hotel),
    SagaStep("charge_card",   charge_card,   refund_card),
    SagaStep("book_flight",   book_flight,   cancel_flight),
])
saga.execute({"user_id": "u_123", "trip_id": "t_456"})

Orchestration vs. choreography

Two flavors:

Orchestration (above): a central coordinator drives each step. Easier to reason about and debug, but the orchestrator becomes a critical service.
Choreography: each service listens for events and decides what to do next. No central point, but the flow is implicit — to understand it, you have to read every subscriber.

Start with orchestration. Move to choreography only when the orchestrator becomes a bottleneck or you have genuinely independent teams owning each step.

Tradeoffs

Sagas give you eventual consistency, not atomicity. There will be moments when a hotel is reserved but the card hasn't been charged yet — your system must tolerate that. Every compensation must be idempotent because it might be retried. And if a compensation itself fails, you need a manual intervention path; don't pretend the system can always self-heal.

5. Asynchronous Messaging

How it works

Synchronous calls couple availability: if Service B is down, Service A's request fails. Async messaging breaks that coupling. Service A publishes an event to a broker (Kafka, RabbitMQ, NATS, SQS), and Service B consumes it whenever it's ready.

# Producer
import json
from kafka import KafkaProducer

producer = KafkaProducer(
    bootstrap_servers=["kafka:9092"],
    value_serializer=lambda v: json.dumps(v).encode(),
    acks="all",        # Wait for all replicas — durability over latency
    enable_idempotence=True,  # Prevents duplicate messages from retries
)

def on_order_placed(order):
    producer.send("orders.placed", {
        "event_id": order.id,
        "user_id": order.user_id,
        "amount": order.amount,
        "timestamp": order.created_at.isoformat(),
    })

# Consumer (in a different service)
from kafka import KafkaConsumer

consumer = KafkaConsumer(
    "orders.placed",
    bootstrap_servers=["kafka:9092"],
    group_id="inventory-service",
    enable_auto_commit=False,   # Commit only after successful processing
    value_deserializer=lambda v: json.loads(v.decode()),
)

for message in consumer:
    try:
        reserve_inventory(message.value)
        consumer.commit()
    except Exception:
        # Don't commit — message will be redelivered
        log.exception("Failed to process order")

When to use it

Reach for async when the consumer doesn't need to respond immediately, when you have multiple consumers for the same event (one event, many subscribers), or when you want to decouple deployment lifecycles. Order placement → inventory update, audit log, fraud check, email notification — all naturally async.

Tradeoffs

Async is harder to debug. A request that used to be one HTTP call is now a chain of events across topics, with retries, dead-letter queues, and ordering caveats. You need distributed tracing (OpenTelemetry) to follow a request across services, and you need to design for at-least-once delivery — consumers must be idempotent because the same message will be redelivered occasionally.

6. Service Mesh

How it works

A service mesh (Istio, Linkerd, Consul Connect) puts a lightweight proxy (a "sidecar") next to every service instance. All traffic in and out flows through the sidecar, which handles mTLS, retries, timeouts, load balancing, observability, and traffic shifting — without any code in your service.

A typical Istio config that routes 10% of traffic to a new version of a service:

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: order-service
spec:
  hosts:
    - order-service
  http:
    - route:
        - destination:
            host: order-service
            subset: v1
          weight: 90
        - destination:
            host: order-service
            subset: v2
          weight: 10

When to use it

A service mesh starts paying for itself somewhere around 20–30 services, when the cost of reimplementing mTLS, retries, and observability in every service exceeds the operational cost of running the mesh. Below that, a good HTTP client library and a few Kubernetes primitives will do.

Tradeoffs

A mesh is operationally heavy. You're adding a proxy to every pod (memory, CPU, latency), a control plane to manage, and a new failure mode to debug. The benefit is that all your services get consistent security, retry behavior, and telemetry for free. The cost is real complexity, and it's not the first thing you should reach for.

Decision Matrix

Problem	Pattern	When to skip it
Clients shouldn't know about your internal services	API Gateway	You have only one or two services
Service instances are dynamic	Service Discovery	You're on Kubernetes (you already have it)
Downstream failures shouldn't take you down	Circuit Breaker	You only make in-process calls
Multi-service transaction without distributed locks	Saga	The operation fits in a single service's database
Decouple producers from consumers	Async messaging	You need a synchronous response and can tolerate the coupling
Multiple read patterns over the same data	CQRS	One model serves all read patterns well
Consistent security, retries, telemetry across many services	Service Mesh	You have fewer than ~20 services
Real-time data pipeline across services	Event streaming (Kafka)	Your throughput fits in a queue

Common Mistakes Across All Patterns

1. Splitting by technical layer, not business capability. "Database service," "API service," "validation service" is not microservices — it's a layered monolith spread across machines. Split along business boundaries (orders, payments, inventory), where each service owns a coherent capability and its data.

2. Sharing a database between services. The moment two services read or write the same tables, you've coupled their schemas and deployment lifecycles. They're now one service in two processes. Each service owns its data; everything else goes through its API.

3. Synchronous chains. Service A calls B calls C calls D, all synchronously. The latency multiplies, the failure modes compound, and any one slow service freezes the whole chain. Break the chain with async messaging where you can.

4. No distributed tracing. Once you have more than three services, you cannot debug production without trace IDs that propagate through every call and event. Add OpenTelemetry on day one — retrofitting it later is painful.

5. Inconsistent error contracts. Each service returns errors in a different shape. Standardize early — pick one error format (RFC 7807 Problem Details is a good default) and enforce it across every service.

6. Microservices for a team of three. The cost of microservices is mostly organizational: independent deploys, on-call rotations, service ownership. If you have one team, a well-structured monolith ships faster and breaks less. Adopt microservices when your team structure starts forcing the split, not before.

Conclusion

Microservices are a response to organizational scale, not a default architecture. The patterns above exist because distributed systems introduce problems monoliths don't have — partial failure, eventual consistency, network latency — and each pattern solves one of those problems at the cost of complexity somewhere else.

Pick the smallest set of patterns that solves your actual problems. Add the next one only when the pain of not having it exceeds the cost of operating it. A two-service system with an API gateway and good observability beats a six-service system with a mesh, a saga orchestrator, and a CQRS pipeline that the team can't fully explain.

To recap:

API Gateway when clients shouldn't see your internal topology.
Service Discovery when instances move (and use what your platform gives you).
Circuit Breaker around every synchronous call you don't fully control.
Saga when a transaction has to span services — orchestration first, choreography later.
Async messaging to decouple lifecycles and fan out events.
Service Mesh once the cost of reimplementing security and observability per-service exceeds the cost of running the mesh.

Start with the decision matrix. Read the source material for whichever pattern you adopt — Sam Newman's Building Microservices, Chris Richardson's microservices.io, and the original Netflix and Amazon engineering blogs are far more honest about tradeoffs than most vendor documentation.

I wrote this after seeing a team try to implement a Service Mesh for a system with only 3 services. What’s the most 'over-engineered' setup you’ve encountered lately?

Securing Web APIs

Shoumik Chakravarty — Sun, 24 May 2026 21:20:22 +0000

A Practical Guide to Authentication & Authorization Methods

Most API security incidents don't happen because attackers found a clever zero-day. They happen because a developer grabbed the first auth pattern that came to mind, shipped it, and moved on.

I've seen API keys committed to public repos, JWTs without expiry running in production, and OAuth flows that skip PKCE on mobile clients. These aren't exotic mistakes — they're the default outcome when engineers don't have a clear map of what each method does, when it fits, and where it breaks down.

This guide gives you that map. We'll cover every major authentication and authorization method used to secure web APIs today, with code examples in Python and a decision matrix at the end so you can match the right tool to your specific context.

Authentication vs. Authorization — Get This Right First

These two words are often used interchangeably. That's a problem, because conflating them leads to real vulnerabilities.

Authentication answers: Who are you? It verifies identity.
Authorization answers: What are you allowed to do? It enforces permissions.

A request can be authenticated (we know it's from User A) but unauthorized (User A doesn't have access to this resource). A system that only checks "is this a valid token?" without checking "does this token have permission to do this?" is wide open to privilege escalation.

Keep both in mind as we go through each method.

1. API Keys

How it works

An API key is a long, random string generated by the server and shared with the client. The client sends it on every request, typically in a header:

GET /v1/data HTTP/1.1
Host: api.example.com
X-API-Key: sk_live_a3f8c2d1e9b7...

On the server side, you validate it against your store:

import secrets
from functools import wraps
from flask import Flask, request, jsonify

app = Flask(__name__)

# In production, store these in a database with metadata
# (owner, scopes, rate limit tier, created_at, last_used)
VALID_KEYS = {
    "sk_live_a3f8c2d1e9b7abc123": {"owner": "client_A", "scopes": ["read"]},
    "sk_live_z9y8x7w6v5u4t3s2r1": {"owner": "client_B", "scopes": ["read", "write"]},
}

def require_api_key(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        key = request.headers.get("X-API-Key")
        if not key or key not in VALID_KEYS:
            return jsonify({"error": "Invalid or missing API key"}), 401
        request.api_client = VALID_KEYS[key]
        return f(*args, **kwargs)
    return decorated

@app.route("/v1/data")
@require_api_key
def get_data():
    return jsonify({"message": f"Hello, {request.api_client['owner']}"})

When to use it

API keys work well for server-to-server communication where the client is a known system (not an end user), especially for public APIs where you want to track usage per consumer, enforce rate limits, or tier access. They're also the right choice for simple internal tooling where OAuth 2.0 would be overkill.

Security tradeoffs

Keys don't expire by default — a leaked key is valid until you rotate it manually.
They carry no user identity, only client identity.
Never put them in URLs (they end up in server logs). Always use headers.
Use secrets.compare_digest() instead of == to prevent timing attacks when comparing keys.

2. Basic Authentication

How it works

The client encodes username:password in Base64 and sends it in the Authorization header on every request:

GET /v1/resource HTTP/1.1
Authorization: Basic c2hvdW1pazpteXBhc3N3b3Jk

import base64
from flask import request, jsonify

def check_basic_auth():
    auth = request.headers.get("Authorization", "")
    if not auth.startswith("Basic "):
        return None
    try:
        decoded = base64.b64decode(auth[6:]).decode("utf-8")
        username, password = decoded.split(":", 1)
        return username, password
    except Exception:
        return None

When to use it

Basic Auth is appropriate for internal tools, admin dashboards behind a VPN, or simple scripts that call internal APIs. It is always required over HTTPS — Base64 is encoding, not encryption, and credentials are trivially reversible over plain HTTP.

Security tradeoffs

Credentials are sent on every single request. One intercepted request = credentials compromised.
No token expiry, no scoping, no revocation without a password change.
Avoid for any externally exposed or user-facing API. It has no place in a mobile or browser client.

3. JWT — JSON Web Tokens

How it works

A JWT is a self-contained, signed token with three Base64URL-encoded parts: a header (algorithm), a payload (claims), and a signature. The server signs it on login; the client sends it back on every subsequent request. The server verifies the signature without hitting a database.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9   ← header
.eyJ1c2VyX2lkIjoiMTIzIiwiZXhwIjoxNzE...  ← payload
.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_...  ← signature

import jwt
import datetime
from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET_KEY = "use-a-strong-secret-from-env-not-hardcoded"

def generate_token(user_id: str) -> str:
    now = datetime.datetime.now(datetime.timezone.utc)
    payload = {
        "sub": user_id,
        "iat": now,
        "exp": now + datetime.timedelta(hours=1),
        "scopes": ["read", "write"],
    }
    return jwt.encode(payload, SECRET_KEY, algorithm="HS256")

def verify_token(token: str) -> dict:
    try:
        # Always specify algorithms explicitly — never pass algorithms=None
        return jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
    except jwt.ExpiredSignatureError:
        raise ValueError("Token has expired")
    except jwt.InvalidTokenError:
        raise ValueError("Invalid token")

@app.route("/login", methods=["POST"])
def login():
    # Validate credentials here (omitted for brevity)
    token = generate_token(user_id="user_123")
    return jsonify({"access_token": token, "token_type": "Bearer"})

@app.route("/v1/profile")
def profile():
    auth = request.headers.get("Authorization", "")
    if not auth.startswith("Bearer "):
        return jsonify({"error": "Missing token"}), 401
    try:
        claims = verify_token(auth[7:])
        return jsonify({"user_id": claims["sub"]})
    except ValueError as e:
        return jsonify({"error": str(e)}), 401

When to use it

JWTs shine in stateless, distributed systems — microservices, APIs behind a CDN, or anywhere you can't share session state between servers. They're the standard for single-page apps and mobile clients that authenticate once and carry claims across services.

The most common JWT mistakes

Mistake	Consequence	Fix
`alg: none` accepted	Anyone can forge a valid token	Always specify `algorithms=["HS256"]` explicitly
No expiry (`exp` claim missing)	Leaked tokens are valid forever	Always set `exp`; 15–60 min for access tokens
Secret stored in code	Any repo leak = all tokens compromised	Load from environment variable or secrets manager
Storing JWT in localStorage	XSS can steal it	Use `HttpOnly` cookies or a BFF pattern
Trusting `alg` header from client	Algorithm confusion attacks	Pin algorithm server-side

4. OAuth 2.0

How it works

OAuth 2.0 is a delegation framework, not an authentication protocol. It lets a user grant a third-party application limited access to their resources without sharing their password.

The most important flows:

Authorization Code + PKCE (for browser/mobile clients — the only safe flow for public clients):

User → App → Authorization Server
  ← Authorization Code
App → Authorization Server (code + PKCE verifier)
  ← Access Token + Refresh Token
App → Resource Server (Access Token)
  ← Protected Resource

Client Credentials (for machine-to-machine, no user involved):

import httpx

def get_machine_token(client_id: str, client_secret: str, token_url: str) -> str:
    response = httpx.post(token_url, data={
        "grant_type": "client_credentials",
        "client_id": client_id,
        "client_secret": client_secret,
        "scope": "api:read api:write",
    })
    response.raise_for_status()
    return response.json()["access_token"]

# Use the token
token = get_machine_token(
    client_id="my-service",
    client_secret="from-env",
    token_url="https://auth.example.com/oauth/token"
)

headers = {"Authorization": f"Bearer {token}"}

When to use it

Use OAuth 2.0 whenever you need delegated access — a user authorizing your app to act on their behalf with another service (Google Drive, GitHub, Stripe). Also use Client Credentials for any service-to-service communication within a trusted internal network.

Critical: always use PKCE for public clients

PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks. Any OAuth flow running in a browser or mobile app that cannot securely store a client secret must use PKCE. It is no longer optional — the OAuth 2.1 draft mandates it for all flows.

5. OpenID Connect (OIDC)

How it works

OpenID Connect is an authentication layer built on top of OAuth 2.0. While OAuth 2.0 says "here is an access token that grants you access to a resource," OIDC adds an ID Token (a JWT) that asserts the user's identity.

# After OAuth flow completes, decode the ID token
import jwt
from jwt import PyJWKClient

def verify_id_token(id_token: str, issuer: str, client_id: str) -> dict:
    # Fetch public keys from the provider's JWKS endpoint
    jwks_client = PyJWKClient(f"{issuer}/.well-known/jwks.json")
    signing_key = jwks_client.get_signing_key_from_jwt(id_token)

    return jwt.decode(
        id_token,
        signing_key.key,
        algorithms=["RS256"],
        audience=client_id,
        issuer=issuer,
    )

claims = verify_id_token(
    id_token=token_response["id_token"],
    issuer="https://accounts.google.com",
    client_id="your-client-id",
)
print(claims["email"])   # Verified user email
print(claims["sub"])     # Stable user identifier

When to use it

Any time you need "Sign in with Google/GitHub/Microsoft" or need to verify who the user is (not just what they can access), OIDC is the right choice. It eliminates the need to manage passwords entirely for federated identity scenarios.

6. HMAC Request Signing

How it works

Instead of sending a credential, the client uses a shared secret to generate a cryptographic signature of the request itself — the method, URL, timestamp, and body. The server recomputes the signature and compares.

import hmac
import hashlib
import time
import base64

def sign_request(method: str, path: str, body: bytes, secret: str) -> dict:
    timestamp = str(int(time.time()))
    message = f"{method}\n{path}\n{timestamp}\n{hashlib.sha256(body).hexdigest()}"
    signature = base64.b64encode(
        hmac.new(secret.encode(), message.encode(), hashlib.sha256).digest()
    ).decode()
    return {
        "X-Timestamp": timestamp,
        "X-Signature": signature,
    }

def verify_request(method: str, path: str, body: bytes,
                   secret: str, headers: dict) -> bool:
    timestamp = headers.get("X-Timestamp", "")
    # Reject requests older than 5 minutes — prevents replay attacks
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = sign_request(method, path, body, secret)
    return hmac.compare_digest(headers.get("X-Signature", ""), expected["X-Signature"])

When to use it

HMAC signing is the right choice for webhooks (Stripe, GitHub, and Twilio all use it), high-integrity financial APIs, and scenarios where you need to prove that a request hasn't been tampered with in transit. AWS Signature Version 4 is HMAC under the hood.

Why it's stronger than API keys for sensitive operations

An API key proves identity but not integrity. If an attacker can intercept and modify a request, the key is still valid. HMAC signs the entire request, so any modification breaks the signature. It also includes a timestamp, preventing replay attacks.

7. Mutual TLS (mTLS)

How it works

In standard TLS, only the server presents a certificate to prove its identity. In mTLS, both the client and server present certificates. This means the server cryptographically verifies the client's identity at the transport layer — before any application code runs.

import ssl
import httpx

# Client presents its certificate on every request
ssl_context = ssl.create_default_context(ssl.Purpose.SERVER_AUTH)
ssl_context.load_verify_locations("ca-cert.pem")          # Trust this CA
ssl_context.load_cert_chain("client-cert.pem", "client-key.pem")  # Our identity

with httpx.Client(verify=ssl_context) as client:
    response = client.get("https://internal-service.example.com/api/data")
    print(response.json())

On the server (nginx configuration example):

server {
    listen 443 ssl;
    ssl_certificate      /etc/ssl/server-cert.pem;
    ssl_certificate_key  /etc/ssl/server-key.pem;
    ssl_client_certificate /etc/ssl/ca-cert.pem;
    ssl_verify_client    on;   # Reject any request without a valid client cert

    location /api/ {
        proxy_pass http://app:8000;
        proxy_set_header X-Client-Cert $ssl_client_cert;
    }
}

When to use it

mTLS is the standard for zero-trust architectures, service meshes (Istio, Linkerd), and any microservice communication where you need hardware-level proof of identity. If you're running services in Kubernetes and want no implicit trust between pods, mTLS is the foundation. It is operationally complex (certificate rotation, PKI management) but offers the strongest guarantees.

Decision Matrix

Use this table to match your scenario to the right method:

Scenario	Recommended Method	Why
Public API — third-party developers	API Keys	Simple to issue, rotate, and rate-limit per client
User logs in, gets access to their data	JWT + OAuth 2.0	Stateless identity + delegated access
"Sign in with Google/GitHub"	OpenID Connect	Federated identity; no password management
Mobile / SPA accessing your API	OAuth 2.0 (PKCE)	PKCE protects public clients; never Client Credentials here
Service A calls Service B internally	OAuth 2.0 (Client Credentials) or mTLS	No user involved; machine-to-machine trust
Webhook endpoint receiving events	HMAC signature verification	Verify payload integrity and origin
Zero-trust / service mesh	mTLS	Transport-layer mutual identity, before any app code
Internal admin tool / script	Basic Auth over HTTPS	Simple, acceptable for low-risk internal use only
High-integrity financial / audit API	HMAC + JWT combined	Identity (JWT) + tamper-evidence (HMAC)

Common Mistakes Across All Methods

1. Mixing up 401 and 403
Return 401 Unauthorized when the request has no valid credentials. Return 403 Forbidden when credentials are valid but the user lacks permission. Many APIs return 403 for everything — this breaks standard OAuth client libraries and confuses consumers.

2. Not validating token audience (aud)
A JWT from your auth server for Service A should not be accepted by Service B. Always validate the aud claim. An attacker who obtains a valid token for one service shouldn't be able to reuse it elsewhere.

3. Logging sensitive headers
It's shockingly common to log the full Authorization header in debug mode. One log aggregation misconfiguration and those tokens are in your SIEM or your cloud provider's log storage. Scrub auth headers before logging.

4. No token rotation
Access tokens expire (they should). Refresh tokens don't have to, but they need to be rotatable. Implement refresh token rotation — when a refresh token is used, issue a new one and invalidate the old one. If you detect reuse of an already-rotated token, revoke the entire family.

5. Trusting client-provided claims
Your API should verify tokens, not trust whatever claims a client sends in a custom header. Never do user_id = request.headers.get("X-User-Id") as your authorization check.

Conclusion

There's no single "best" authentication method — there's only the right method for the trust model, client type, and sensitivity level of your specific API. The biggest mistake isn't choosing the wrong method; it's treating auth as an afterthought and never revisiting the decision as your system evolves.

To recap:

API Keys for known clients and developer APIs.
Basic Auth only for internal tooling over HTTPS.
JWT for stateless, distributed systems.
OAuth 2.0 for delegated access and third-party integrations.
OIDC whenever you need verified user identity.
HMAC for webhooks and tamper-evident request signing.
mTLS for zero-trust service-to-service communication.

Start with the decision matrix. Then read the spec for whichever method you choose — the RFCs and official documentation are far shorter than you'd expect, and reading them directly will save you from the edge cases that bite teams in production.