TUTORIAL

How to Build a Secure API Gateway

Design a secure API gateway that handles authentication, rate limiting, request validation, and threat protection for backend services.

Problem

Your backend services are directly exposed to clients, making them vulnerable to abuse, unauthorized access, and malformed requests. You need a secure API gateway as a single entry point that enforces security policies before requests reach your services.

Prerequisites

Understanding of HTTP APIs and REST/GraphQL patterns
Familiarity with authentication mechanisms (API keys, JWT, OAuth 2.0)
Knowledge of OpenAPI/Swagger specifications

Steps

1. Define the gateway security layers

Structure the gateway with layered security: (1) TLS termination with modern cipher suites, (2) request size and rate limits, (3) authentication (API key, JWT, OAuth), (4) authorization (scope/role checks), (5) input validation against schema, (6) threat protection (SQL injection, XSS, path traversal), (7) response filtering. Each layer can reject the request before it reaches the backend.
Input
```
incoming HTTP request
```
Output
```
layers: TLS -> rateLimit -> auth -> authz -> validate -> threats -> backend
```
2. Implement authentication and authorization

Support multiple auth methods: API keys for simple service-to-service, JWT for user sessions, OAuth 2.0 for delegated access. Validate JWT signatures using the issuer's public key, check expiration and audience claims. For API keys, hash-compare against stored hashes (never store plaintext). Enforce scope-based authorization: each endpoint requires specific scopes. Use the JWT parser to inspect tokens and the API spec validator to check endpoints.
Input
```
Authorization: Bearer eyJhbG...
```
Output
```
auth: valid | user: alice | scopes: [read:data, write:data]
```
3. Configure rate limiting and request validation

Apply tiered rate limits: per-IP, per-user, per-API-key, and global. Use token bucket or sliding window algorithms. Reject requests exceeding limits with HTTP 429 and Retry-After header. Validate every request against the OpenAPI schema: check required fields, types, formats, and value ranges. Reject malformed requests with HTTP 400 before they reach the backend. Use the API spec validator to enforce schema compliance.
Input
```
100 requests/second from one IP
```
Output
```
HTTP 429 Too Many Requests | Retry-After: 1
```
4. Add threat protection and observability

Filter requests for common attack patterns: SQL injection (malicious quotes, UNION), XSS (script tags, event handlers), path traversal (../), and command injection. Use allow-lists rather than deny-lists where possible. Log all requests with correlation IDs, auth results, response codes, and latency. Monitor for anomalies: spike in 4xx/5xx, unusual request patterns, auth failures. Sanitize all error messages to avoid leaking internal details.
Input
```
query: ' OR 1=1 --
```
Output
```
blocked: SQL injection pattern | HTTP 400
```

Expected result

A secure API gateway that authenticates, authorizes, rate-limits, validates, and protects all backend services from abuse and attacks, with full observability.

Common errors

Validating JWT signature but not expiration or audience: Check all claims: signature, exp, nbf, iss, aud, and scope. A valid signature with expired token is still invalid.
Using deny-lists for threat protection: Deny-lists are incomplete and bypassable. Use allow-lists (strict input validation against schema) as the primary defense, with deny-lists as supplementary.
Rate limiting only by IP: IP limits are bypassable via rotation and fail behind shared NAT. Apply per-user and per-API-key limits in addition to per-IP.

Troubleshooting

If legitimate users are rate-limited, implement tiered limits (higher for authenticated, lower for anonymous) and allow burst tokens.
For GraphQL gateways, add query complexity analysis and depth limiting to prevent resource exhaustion via nested queries.
If the gateway becomes a bottleneck, ensure it is stateless (use external Redis for rate limit counters) and horizontally scalable.

Security limits

The gateway is a high-value target — compromise of the gateway compromises all services behind it. Secure it with the same rigor as critical services.
All token validation and policy enforcement happen at the gateway; backend services should still verify auth independently (defense in depth).
Error messages must not leak internal architecture, stack traces, or SQL errors.