API key management in Microservices - System Design Guide

Problem Statement

Without proper API key management, unauthorized users can access services, leading to data breaches and service misuse. Additionally, lack of control over API keys makes it hard to revoke or rotate keys, causing security risks and operational challenges.

Solution

API key management controls access by issuing unique keys to clients and validating them on each request. It includes generating, storing, rotating, and revoking keys securely, often integrated with authentication and authorization systems to enforce usage policies.

Architecture

Client App

→API Gateway

↓

This diagram shows a client sending requests with an API key to the API Gateway, which validates the key against a Key Database before forwarding the request to microservices.

Trade-offs

✓ Pros

→

Prevents unauthorized access by validating API keys on every request.

→

Allows fine-grained control over client permissions and usage limits.

→

Supports key rotation and revocation to maintain security over time.

→

Enables monitoring and auditing of API usage per client.

✗ Cons

→

Adds latency due to key validation on each request.

→

Requires secure storage and management of keys to prevent leaks.

→

Increases system complexity with additional components like key databases and gateways.

Use when your system exposes APIs to external or internal clients requiring controlled access, especially at scale above 1,000 requests per second or when security and usage tracking are critical.

Avoid if your API is strictly internal with trusted clients and low security risk, or if the request volume is very low (under 100 requests per day) where overhead outweighs benefits.

Real World Examples

Stripe

Stripe issues API keys to merchants to securely access payment processing APIs, enabling fine-grained control and easy revocation if keys are compromised.

Google Cloud

Google Cloud uses API keys to authenticate and authorize access to its cloud services, allowing usage tracking and quota enforcement per client.

Twilio

Twilio manages API keys to control access to its communication APIs, enabling clients to rotate keys regularly and revoke compromised keys without service disruption.

Code Example

The before code exposes an endpoint without any access control. The after code adds a decorator that checks for a valid API key in the request headers and rejects unauthorized requests with a 401 error.

Microservices

### Before: No API key validation
from flask import Flask, request
app = Flask(__name__)

@app.route('/data')
def data():
    return {'message': 'Public data'}


### After: API key validation middleware
from flask import Flask, request, abort
app = Flask(__name__)

VALID_API_KEYS = {'abc123', 'def456'}

def require_api_key(func):
    def wrapper(*args, **kwargs):
        api_key = request.headers.get('X-API-Key')
        if api_key not in VALID_API_KEYS:
            abort(401, 'Invalid or missing API key')
        return func(*args, **kwargs)
    return wrapper

@app.route('/data')
@require_api_key
def data():
    return {'message': 'Protected data'}

Alternatives

OAuth 2.0

Uses token-based authorization with scopes and user consent instead of static API keys.

Use when: Choose OAuth 2.0 when user delegation and fine-grained permission scopes are required.

Mutual TLS Authentication

Clients authenticate using certificates instead of keys, providing stronger identity verification.

Use when: Choose mutual TLS when high security and encrypted client-server communication are mandatory.

JWT (JSON Web Tokens)

Uses signed tokens carrying claims instead of opaque API keys, enabling stateless authentication.

Use when: Choose JWT when you want scalable, stateless authentication with embedded user information.

Summary

API key management prevents unauthorized API access by validating unique keys per client.

It enables control over usage, key rotation, and revocation to maintain security.

Proper management requires secure storage, validation, and integration with API gateways.