Catalog My learning Blog
System Design Roadmap: 100-Day Course for Engineers · Phase 9 · Lesson 83 · 4 min read

API Security Best Practices for System Design

On this page
  1. The breach that needed no hacking skill
  2. API security checklist for every endpoint
  3. What an API gateway can't secure
  4. API security testing: think like an attacker
  5. Check yourself

The breach that needed no hacking skill

An attacker logs into a delivery app with their own account and requests GET /api/orders/10442. They get their order. They try 10443 and get someone else's, with a name, address and phone number. A script later, they have hundreds of thousands. No exploit, no malware: the API simply never checked whether the order belonged to the caller. This flaw, broken object level authorization (BOLA), sits at the top of the OWASP API Security Top 10.

API security checklist for every endpoint

1. Authorize every object. Check ownership on every read and write, in the query itself:

SQL
SELECT * FROM orders WHERE id = @orderId AND customer_id = @callerId;   -- not just WHERE id = @orderId

Random ids (UUIDs) make guessing harder but are not a substitute for the check.

2. Validate input on the server. Client-side validation is for user experience; attackers skip it. Validate types, lengths, ranges and formats; use parameterized queries against SQL injection; reject unexpected fields.

3. Prevent mass assignment. Binding request JSON directly onto an entity lets a caller set isAdmin: true or price: 0. Bind to request DTOs with only the fields a caller may set.

4. Return only what's needed. Don't serialize whole database entities; internal fields and other users' data leak that way. Shape each response on purpose.

5. Rate-limit and limit size. Per user and per IP limits on login, password reset and expensive endpoints (Day 72), plus maximum request body sizes and pagination limits.

6. Authenticate properly. Short-lived tokens, audience and scope checks (Day 82), no API keys in URLs where they end up in logs.

7. Keep secrets out of code. Connection strings, keys and signing secrets live in a secret store (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault), injected at runtime, rotated regularly. Scan repositories for leaked secrets.

8. Encrypt in transit everywhere, including internal calls (Days 84 and 85).

9. Log security events without logging secrets: failed logins, authorization failures, rate-limit hits. Alert on spikes, such as one user hitting thousands of 403s or 404s.

10. Never fetch a URL the caller chose without checks. Features like "import an image from a URL" or "send webhooks to this address" make your server issue requests. An attacker can point them at internal targets: http://localhost:8080/admin, an internal service, or the cloud metadata endpoint at 169.254.169.254, which can hand out the server's cloud credentials. This is server-side request forgery (SSRF), and it was central to the 2019 Capital One breach. Allow only expected schemes and hosts, resolve the address and refuse private and link-local ranges, and on AWS require IMDSv2, which blocks the simplest version of this attack.

11. Hide internals in errors. Stack traces, SQL text and framework versions in error responses help attackers map your system. In ASP.NET Core, the developer exception page belongs only in the Development environment; production returns Problem Details (Day 14) with a correlation id the support team can look up.

Layered API defenses: gateway policies at the edge, then authentication, object-level authorization, validation and limited responses in each service.
Layered API defenses: gateway policies at the edge, then authentication, object-level authorization, validation and limited responses in each service.

What an API gateway can't secure

An API gateway (Day 18) centralizes TLS, token validation, rate limits and request size limits. It can't do object-level authorization or business validation; it doesn't know who owns order 10443. Those checks belong in the service that owns the data.

API security testing: think like an attacker

  • Automated tests that call every endpoint as user A with user B's ids, expecting 403 or 404.
  • Dependency scanning for vulnerable libraries.
  • Periodic penetration tests and API security scanners against staging.

Check yourself

Broken object level authorization: an endpoint returns or changes an object without checking the caller may access it. Check ownership on every object access, ideally in the query itself.

Attackers don't use your client: they call the API directly with tools like curl or scripts, skipping every check in the browser or app. Client-side validation is for a good user experience; only validation on the server, for every request, actually protects the system.

SSRF: they gave the cloud metadata address, and the server fetched it from inside the network. Allow-list hosts, block private and link-local addresses, and require IMDSv2.

Mass assignment: a caller can set fields they shouldn't, like roles or account status. Bind to a DTO containing only allowed fields.

An API returns whole objects, including fields the client doesn't need, such as internal ids or other users' email addresses, trusting the client to hide them. Return explicit response models with only the fields each endpoint should expose.