/gateway

API Security Patterns

Scope: This file covers authentication, authorization, CORS, input validation, and security review patterns. For rate-limit algorithms, headers (RateLimit-* / legacy X-RateLimit-*), 429 + Retry-After semantics, and distributed enforcement, see rate-limit-patterns.md (the canonical source).

Authentication Methods

CORS Configuration

const corsOptions = {
  origin: ['https://app.example.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
  maxAge: 86400,
};

Input Validation Checklist

• Validate Content-Type header
• Validate request body against schema
• Sanitize string inputs
• Limit request body size
• Validate path and query parameters

Security Review Checklist

Authentication

• Endpoints require authentication (unless public)
• Token validation documented
• Token expiration handled

Authorization

• Resource ownership verified
• Role-based access defined
• Cross-tenant access prevented

Input Validation

• All inputs validated
• Size limits defined
• Type coercion avoided
• SQL/NoSQL injection prevented
• Path traversal prevented

Output Security

• Sensitive data excluded from responses
• Error messages don't leak internals
• CORS configured correctly
• Security headers present

Rate Limiting

• Limits defined per endpoint
• Limits documented
• 429 response includes Retry-After

API Security 2025

OAuth 2.1 Consolidation

OAuth 2.1 consolidates OAuth 2.0 + best practices from Security BCP (RFC 9700) into a single spec.

DPoP (Demonstrating Proof of Possession)

DPoP (RFC 9449) binds access tokens to a client's key pair, preventing token replay attacks.

• Client generates an asymmetric key pair (ES256 / RS256) per session.
• Each request includes a DPoP header with a signed JWT proof containing the request method, URI, and timestamp.
• Server verifies proof and rejects tokens used without the matching key.

Authorization: DPoP <access_token>
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand...

API Key Best Practices

Rate Limiting Headers

See rate-limit-patterns.md for the IETF RateLimit / RateLimit-Policy draft header spec, legacy X-RateLimit-* headers, and 429 + Retry-After body conventions.

API Gateway Patterns

BFF (Backend for Frontend)

Each frontend type (web, mobile, third-party) gets a dedicated API gateway facade.

Rules:

1. BFF owns aggregation logic — never expose raw microservice contracts to clients.
2. One BFF per client type (not per team) — avoid BFF proliferation.
3. BFF does not contain business logic — delegate to domain services.
4. Co-locate BFF code with the frontend team that owns it.

Circuit Breaker

Prevents cascading failures when downstream services are degraded.

State transitions:

CLOSED → (failure threshold exceeded) → OPEN → (timeout elapsed) → HALF-OPEN → (probe success) → CLOSED
                                                                              → (probe failure) → OPEN

Retry Strategy

Exponential backoff with jitter prevents thundering herd after outages.

Rules:

• Only retry on idempotent methods (GET, PUT, DELETE) or when Idempotency-Key is used.
• Never retry on 4xx errors except 429 Too Many Requests (honor Retry-After).
• Include Idempotency-Key header on POST retries to prevent duplicate resource creation.

POST /v1/payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json