Structured approach to building secure APIs, covering OWASP API Security Top 10 (2023), secure design patterns, and verification checklists. Apply these guidelines throughout the API development lifecycle — from threat modeling to deployment monitoring.
Secure API Development Lifecycle
Phase 1: API Threat Modeling and Design
- Identify API attack surfaces: public endpoints, authenticated endpoints, admin endpoints, webhooks, third-party integrations
- Map data flows: what sensitive data crosses each API boundary
- Define authorization model: which users/roles access which resources and properties
- Design security controls:
- Centralized authentication (OAuth2/OIDC at API gateway)
- Object-level authorization at data access layer
- Schema-based input validation at every endpoint
- Rate limiting per endpoint sensitivity
- API versioning with deprecation strategy
Phase 2: Secure Implementation
Critical API Security Rules
| Never | Instead |
|---|---|
| Return full objects (to_dict/to_json) | Explicit response schemas with cherry-picked fields |
| Accept arbitrary fields for update | Allowlisted update schemas (prevent mass assignment) |
| Use sequential/guessable IDs in URLs | UUIDs/GUIDs for resource identifiers |
| Trust object ID alone for access | Check object ownership against authenticated user |
| Rely on client-side role checks | Server-side RBAC/ABAC middleware |
| Accept unlimited query params/body | Schema validation with size/type/range limits |
| Skip rate limiting on any endpoint | Rate limit ALL endpoints, stricter on auth/business flows |
| Return stack traces in errors | RFC 7807 Problem Details with generic messages |
| Trust third-party API responses | Validate and sanitize all external API data |
| Put API keys in URLs | Use Authorization header or secure key vault |
| Use wildcard CORS with credentials | Explicit origin allowlist |
| Allow unlimited GraphQL depth/complexity | Query depth + complexity + batch limits |
Reference detailed guides:
- For OWASP API Top 10 with code examples: See references/owasp-api-top-10.md
- For secure API design patterns: See references/secure-api-design.md
Phase 3: API Security Verification
- Schema Validation — Lint OpenAPI spec for security issues (Spectral)
- Static Analysis — Run SAST on API code (Semgrep, bandit)
- Contract Testing — Verify API behavior matches spec (Schemathesis, Dredd)
- Dynamic Testing — Run DAST against running API (OWASP ZAP, Burp Suite)
- Authorization Testing — Test every endpoint with wrong user/role/anonymous
- Rate Limit Testing — Verify all endpoints enforce limits
- Code Review — Apply API security checklists
Reference: See references/api-security-checklist.md
Phase 4: Deployment and Monitoring
- API gateway: auth offloading, rate limiting, request logging
- TLS 1.2+ enforcement, HSTS, security headers
- Structured logging (no tokens/PII in logs)
- Anomaly detection and alerting on security events
- API inventory management and version deprecation
- Incident response plan for API breaches
OWASP API Security Top 10 (2023) Quick Reference
| # | Risk | Key Concern | Primary Prevention |
|---|---|---|---|
| API1 | Broken Object Level Authorization | Accessing other users' resources by manipulating IDs | Object ownership check at data layer, use GUIDs |
| API2 | Broken Authentication | Weak auth, credential stuffing, JWT flaws | OAuth2/OIDC, short-lived tokens, rate limit auth |
| API3 | Broken Object Property Level Authorization | Excessive data exposure + mass assignment | Explicit response/request schemas, field allowlists |
| API4 | Unrestricted Resource Consumption | No rate/size/cost limits, GraphQL batching | Rate limiting, pagination caps, spending alerts |
| API5 | Broken Function Level Authorization | Regular users accessing admin functions | RBAC middleware, deny by default, test all roles |
| API6 | Unrestricted Access to Sensitive Business Flows | Automating business-critical operations (scalping, spam) | CAPTCHA, device fingerprinting, behavior analysis |
| API7 | Server Side Request Forgery | API fetches user-supplied URLs | URL allowlisting, block private IPs, disable redirects |
| API8 | Security Misconfiguration | Missing headers, CORS *, verbose errors, debug endpoints | Hardened defaults, security headers, minimal errors |
| API9 | Improper Inventory Management | Shadow APIs, deprecated versions, no documentation | API inventory, OpenAPI in CI/CD, retirement plans |
| API10 | Unsafe Consumption of APIs | Trusting third-party API data without validation | Validate all external data, enforce TLS, set timeouts |
For detailed attack scenarios and code examples: See references/owasp-api-top-10.md
API Security Review Workflow
Step-by-step procedure for reviewing API security:
- Map the API surface — List all endpoints, methods, auth requirements, and data flows. Check for undocumented/shadow endpoints.
- Check authentication — Verify every non-public endpoint requires valid authentication. Test with missing/expired/malformed tokens.
- Check object-level authorization (BOLA) — For every endpoint accepting resource IDs, verify users can only access their own resources.
- Check function-level authorization (BFLA) — Verify admin endpoints reject non-admin users. Test horizontal and vertical privilege escalation.
- Check property-level authorization — Verify responses only include authorized fields. Test mass assignment by sending extra fields in updates.
- Validate input handling — Check schema validation on all inputs. Test with oversized payloads, unexpected types, injection payloads.
- Check rate limiting — Verify limits on all endpoints, especially auth, business-critical, and resource-intensive operations.
- Check error handling — Verify no sensitive info in error responses. Test with invalid inputs, missing resources, server errors.
- Review third-party integrations — Verify external API responses are validated. Check for SSRF in URL-accepting endpoints.
- Check API inventory — Verify no deprecated/shadow endpoints are live. Check documentation matches reality.
- Report findings — Severity (Critical/High/Medium/Low), endpoint, vulnerable request, explanation, fix with code example.
API Security Testing Quick Commands
# === OpenAPI Spec Linting ===
npm install -g @stoplight/spectral-cli && spectral lint openapi.yaml
# === Property-based API Testing ===
pip install schemathesis && schemathesis run --checks all http://localhost:8000/openapi.json
# === Dynamic Security Scanning ===
docker run -t ghcr.io/zaproxy/zaproxy:stable zap-api-scan.py -t http://target:8000/openapi.json -f openapi
# === API Fuzzing ===
# nuclei -u http://target:8000 -t api/
# === Static Analysis (Python API) ===
pip install bandit && bandit -r src/ -f json
pip install semgrep && semgrep --config=p/python --config=p/owasp-top-ten src/
Reference Files
- references/owasp-api-top-10.md — Detailed OWASP API Security Top 10 (2023) with attack scenarios, vulnerable → secure code examples for REST and GraphQL APIs
- references/secure-api-design.md — Secure API design patterns: authentication (OAuth2, JWT, API keys, mTLS), authorization (RBAC/ABAC), input validation, rate limiting, CORS, error handling, API gateway, monitoring
- references/api-security-checklist.md — Actionable checklists for API design review, auth, input validation, transport security, rate limiting, inventory, deployment, logging, and testing