api-security

name	api-security
description	Use when securing APIs against common attack vectors. Covers rate limiting, CORS configuration, Content Security Policy, security headers, API gateway patterns, and API authentication strategies. USE FOR: API security, rate limiting, CORS, CSP, security headers, API gateway, API authentication, API keys, OAuth for APIs, HTTPS enforcement, request validation DO NOT USE FOR: API design patterns (use dev/backend/api-design), API testing tools (use testing/api-testing), authentication protocol details (use authentication)
license	MIT
metadata	{"displayName":"API Security","author":"Tyler-R-Kendrick"}
compatibility	claude, copilot, cursor
references	[{"title":"OWASP API Security Top 10","url":"https://owasp.org/www-project-api-security/"},{"title":"OWASP REST Security Cheat Sheet","url":"https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html"},{"title":"MDN Web Docs: Content Security Policy (CSP)","url":"https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP"}]

API Security

Overview

APIs are the primary attack surface of modern applications. As architectures shift toward microservices, serverless functions, and third-party integrations, the number of exposed API endpoints grows dramatically. Every endpoint is a potential entry point for attackers. Securing APIs requires a layered approach that includes transport security, authentication, authorization, input validation, rate limiting, and proper response handling. A single misconfigured header or overly permissive CORS policy can expose an entire system.

Security Headers

Security headers instruct browsers and clients on how to handle responses, significantly reducing the attack surface for common web-based attacks.

Header	Purpose	Recommended Value
Strict-Transport-Security	Forces HTTPS connections; prevents protocol downgrade attacks	max-age=31536000; includeSubDomains; preload
X-Content-Type-Options	Prevents MIME type sniffing; ensures browser respects declared content type	nosniff
X-Frame-Options	Prevents clickjacking by controlling whether the page can be framed	DENY (or SAMEORIGIN if framing is required)
Content-Security-Policy	Controls which resources the browser is allowed to load; mitigates XSS	See CSP section below for detailed directives
Referrer-Policy	Controls how much referrer information is sent with requests	strict-origin-when-cross-origin
Permissions-Policy	Restricts access to browser features (camera, microphone, geolocation)	camera=(), microphone=(), geolocation=()
Cache-Control	Prevents caching of sensitive data by intermediaries and browsers	no-store, no-cache, must-revalidate, private
X-Request-Id	Provides a unique identifier for request tracing and correlation	Generate a UUID per request; echo it in the response

For pure JSON APIs that are not serving HTML, a minimal set of headers should include Strict-Transport-Security, X-Content-Type-Options, Cache-Control (for sensitive responses), and X-Request-Id. The full set above is recommended when the API serves content rendered in a browser.

CORS Configuration

What CORS Is

Cross-Origin Resource Sharing (CORS) is a browser-enforced mechanism that controls which origins are permitted to make requests to your API. When a browser makes a cross-origin request, it sends an Origin header; the server must respond with appropriate Access-Control-* headers to allow or deny the request.

Dangerous Misconfigurations

• Wildcard with credentials: Setting Access-Control-Allow-Origin: * together with Access-Control-Allow-Credentials: true is invalid per the specification, but some implementations attempt it. This would allow any website to make authenticated requests to your API.
• Reflecting the Origin header: Dynamically returning whatever origin the request sends without validation is equivalent to a wildcard and defeats the purpose of CORS.
• Overly broad origin patterns: Matching *.example.com without anchoring can be tricked by domains like evil-example.com.

Proper Configuration Example

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Request-Id
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400

Key rules:

• Explicitly list allowed origins; never use wildcard with credentials.
• Restrict allowed methods to only those the API actually supports.
• Restrict allowed headers to those your API requires.
• Set Access-Control-Max-Age to cache preflight responses and reduce latency.

Preflight Requests

Browsers send an OPTIONS preflight request before making "non-simple" requests (those with custom headers, methods other than GET/POST, or non-standard content types). Your API must handle OPTIONS requests and return the appropriate CORS headers with a 204 No Content response. Ensure preflight handling does not require authentication.

Content Security Policy

Content Security Policy (CSP) tells the browser which sources of content are trusted, providing a strong defense against cross-site scripting (XSS) and data injection attacks.

Key Directives

Directive	Purpose	Example Value
default-src	Fallback for all resource types not explicitly configured	'self'
script-src	Controls which scripts can execute	'self' (avoid 'unsafe-inline' and 'unsafe-eval')
style-src	Controls which stylesheets can be applied	'self' 'unsafe-inline' (inline styles often required)
img-src	Controls which image sources are allowed	'self' data: https://cdn.example.com
connect-src	Controls which URLs can be accessed via fetch, XHR, WebSocket	'self' https://api.example.com
frame-ancestors	Controls which origins can embed this page in a frame	'none' (replaces X-Frame-Options)

Example Policies

For a JSON API (minimal CSP since no HTML rendering):

Content-Security-Policy: default-src 'none'; frame-ancestors 'none'

For a web application:

Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' https://api.example.com; frame-ancestors 'none'; base-uri 'self'; form-action 'self'

Monitoring Violations

Use report-uri (deprecated but widely supported) or report-to to receive violation reports without blocking content. Start with Content-Security-Policy-Report-Only to monitor before enforcing:

Content-Security-Policy-Report-Only: default-src 'self'; report-uri /csp-report

Rate Limiting

Rate limiting protects APIs from abuse, brute-force attacks, and denial-of-service attempts by restricting the number of requests a client can make within a given time window.

Algorithms

Algorithm	How It Works	Pros	Cons
Token Bucket	Tokens are added at a fixed rate; each request consumes a token; requests are rejected when the bucket is empty	Allows bursts up to bucket size; smooth average rate	Requires per-client state; bucket size tuning needed
Sliding Window	Counts requests in a rolling time window by combining current and previous window counts	More accurate than fixed window; smooth rate enforcement	Higher memory usage; slightly more complex
Fixed Window	Counts requests in discrete time intervals (e.g., per minute)	Simple to implement; low overhead	Vulnerable to burst at window boundaries (2x burst)
Leaky Bucket	Requests enter a queue (bucket) and are processed at a fixed rate; overflow is rejected	Very smooth output rate; prevents bursts entirely	Can add latency for queued requests; rigid

Response Headers

Include rate limit information in every response so clients can self-regulate:

Header	Purpose
X-RateLimit-Limit	Maximum number of requests allowed in the current window
X-RateLimit-Remaining	Number of requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the current window resets
Retry-After	Seconds to wait before retrying (sent with 429 Too Many Requests)

Tiered Limits by Authentication Level

Tier	Authentication	Rate Limit	Use Case
Anonymous	None	60 requests/hour	Public read-only endpoints
Authenticated	API key or Bearer token	1,000 requests/hour	Standard application usage
Premium	API key with premium plan	10,000 requests/hour	High-volume integrations
Internal	mTLS or service mesh identity	100,000 requests/hour	Service-to-service communication

API Authentication

Different authentication mechanisms suit different contexts. Choose based on the trust level, client type, and security requirements.

Method	Use Case	Security Level	Details
API Keys	Internal services, low-risk public APIs	Low-Medium	Simple to implement; transmitted in headers; easily leaked if not managed; rotate regularly; never embed in client-side code
OAuth 2.0 Bearer Tokens	User-delegated access, third-party integrations	High	Industry standard for delegated authorization; use short-lived access tokens with refresh tokens; validate scopes on every request
mTLS (Mutual TLS)	Service-to-service communication	Very High	Both client and server present certificates; strong identity verification; requires certificate management infrastructure (PKI)
HMAC Signatures	Webhook verification, request integrity	High	Request body is signed with a shared secret; prevents tampering and replay (with timestamp); no credentials transmitted

Key considerations across all methods:

• Always transmit credentials over HTTPS.
• Implement token/key rotation and revocation mechanisms.
• Log authentication events for audit and anomaly detection.
• Use short-lived tokens and refresh mechanisms where possible.

API Gateway Security

An API gateway acts as a centralized entry point for all API traffic, providing a single location to enforce security policies consistently across services.

What an API Gateway Provides

• Authentication and authorization: Validate tokens, API keys, and certificates at the edge before requests reach backend services.
• Rate limiting: Enforce per-client and per-endpoint rate limits centrally.
• Request validation: Validate request schemas (JSON Schema, OpenAPI spec) and reject malformed input before it reaches application logic.
• TLS termination: Handle HTTPS at the gateway; backend services can communicate over a trusted internal network.
• Logging and monitoring: Capture request/response metadata, latency metrics, and error rates in a centralized location.
• IP allowlisting/blocklisting: Restrict access by source IP for internal or partner APIs.
• Request/response transformation: Strip sensitive headers, mask fields, or add security headers uniformly.

Common API Gateways

Gateway	Type	Key Features
Kong	Open source / Enterprise	Plugin ecosystem, declarative config, gRPC support, Kubernetes-native
AWS API Gateway	Managed (AWS)	Lambda integration, usage plans, WAF integration, mutual TLS
Azure API Management	Managed (Azure)	Policy engine, developer portal, built-in caching, multi-region
Envoy	Open source (proxy)	Service mesh integration (Istio), advanced load balancing, extensible via WASM
NGINX	Open source / Commercial	High performance, Lua scripting, broad protocol support

Best Practices

• Enforce HTTPS everywhere — never allow plaintext HTTP for any API endpoint; use HSTS headers to prevent downgrade attacks and configure TLS 1.2 as the minimum supported version.
• Validate all input on the server side — never trust client-side validation alone; validate request bodies against schemas, enforce type and length constraints, and reject unexpected fields.
• Use the principle of least privilege for API scopes — issue tokens with the minimum scopes and permissions required for the specific operation; avoid wildcard or admin scopes for routine operations.
• Implement defense in depth — combine multiple security layers (gateway, authentication, authorization, input validation, rate limiting, monitoring) so that no single control failure results in a breach.
• Return minimal error information — never expose stack traces, internal paths, or database error messages in API responses; use generic error messages with correlation IDs for debugging.
• Log all security-relevant events — record authentication attempts, authorization failures, rate limit hits, and input validation rejections; feed logs into a SIEM for real-time alerting.
• Version your APIs and deprecate securely — maintain security patches across all supported versions; when deprecating, provide clear timelines and ensure old versions are eventually decommissioned.
• Audit third-party API integrations — review the security posture of external APIs your application depends on; validate their responses, enforce timeouts, and implement circuit breakers to prevent cascading failures.