API Security Design

API Security Design

Secure API design protects backend services and data from abuse and the OWASP API Security Top 10 risks - broken object-level authorization (BOLA), broken authentication, broken function-level authorization (BFLA), unrestricted resource consumption, server-side request forgery, and more. On Azure, Azure API Management (APIM) is the primary policy enforcement point, paired with WAF, Entra ID, Key Vault, and Defender for APIs.

When to use

Designing or reviewing the security of APIs - especially external-facing, partner-facing, or sensitive-data APIs - before they go live or as part of a recurring design review.

Do not use this skill for:

• General application or web app security (use security-architecture, threat-modelling)
• API runtime detection and posture only (use defender-for-apis)
• Front-end / SPA design (use web app security guidance)

Pick the right control per OWASP API risk

Rule of thumb: BOLA and BFLA are the top two API risks and cannot be fully fixed at the gateway - the backend must enforce per-object and per-function authorization. The gateway is necessary but not sufficient.

Approach

1. Authentication at the gateway with Entra ID - Require OAuth 2.0 / OpenID Connect via Microsoft Entra ID; validate JWTs at APIM with the validate-jwt policy (issuer, audience, signing key, expiration, required claims). Avoid static API keys as the only control - rotate them aggressively if used at all. Verify: a request with an invalid or expired JWT is rejected at the gateway; logs show the rejection reason.
2. Authorization in the backend - Enforce least-privilege scopes/roles in the JWT, then check object-level and function-level authorization in the backend on every call. The gateway sees the caller; only the backend knows whether the caller owns the object. Verify: a test JWT for user A returns 403 when requesting user B's data, even though the gateway lets the call through.
3. Apply gateway protections (APIM) - Configure: rate-limit and quota policies per subscription/IP/identity, IP filtering for allow-lists, request and response validation against the OpenAPI schema, payload size limits, timeouts, and CORS scoped to known origins. Verify: a request exceeding the rate limit returns 429; an oversized payload is rejected; a request not matching the OpenAPI schema is rejected.
4. Transport and secrets - Enforce TLS 1.2+ on every endpoint, use mTLS to backends where threat model requires it, and store all secrets (backend credentials, signing keys) in Azure Key Vault referenced via APIM named values with a managed identity. No secrets in policy XML, no secrets in code. Verify: no secret literal appears in APIM policies or source repo; APIM uses managed identity to fetch Key Vault references at runtime.
5. Exposure and network controls - Front public APIs with WAF (Application Gateway or Azure Front Door) for L7 protection (OWASP Core Rule Set), and use Private Endpoints to keep backends off the public internet. Internal APIs should not have a public route. Verify: a port scan of the public IP reaches WAF/APIM only; backends are not reachable directly from the internet.
6. Validate input rigorously - Validate against the OpenAPI schema at the gateway; reject unexpected fields, oversized payloads, and malformed types. Backend code re-validates business invariants - never trust the gateway alone. Verify: fuzz testing on the API produces 4xx responses, not 5xx; no input class causes a crash or stack trace leak.
7. Add runtime threat detection - Enable Microsoft Defender for APIs for APIM-fronted APIs to detect runtime threats (suspicious access patterns, sensitive-data exposure, reconnaissance, OWASP-aligned attacks). Verify: a deliberately abusive test client triggers a Defender for APIs alert.
8. Catalog and lifecycle the APIs - Inventory every API in APIM (or your gateway), tag by sensitivity and ownership, and retire deprecated versions on a schedule. Shadow APIs
   • undocumented, unmonitored - are the most common breach path.

Guardrails

• BOLA/BFLA are the top API risks - authorization must be enforced server-side per object and per function. The gateway can see the caller but not which objects they may touch.
• Don't rely on the gateway alone - defence in depth across gateway + backend. Single layers fail; layered controls mean a misconfiguration in one place does not equal breach.
• Validate input against a schema; reject unexpected fields and oversized payloads. The most common API CVE is "we accepted what we did not expect".
• No static API keys as sole authentication. Move to OAuth 2.0 + Entra ID. If keys remain for partner compatibility, rotate aggressively and rate-limit hard.
• Treat the API inventory as an asset - shadow APIs are unmanaged risk. Discovery + catalog is part of API security, not just operations.
• Backend re-validation is not duplication - it is the only place per-object authorization can land safely.

Common anti-patterns

• "We have JWT validation at the gateway, we are secure." Missing BOLA/BFLA checks in the backend - the most common API breach pattern.
• Static API keys with no rate limit and no rotation. Single credential leak = full exposure with no detection.
• No schema validation at the gateway. Backends crash on malformed input and leak stack traces; fuzzing finds bugs in production rather than in test.
• Secrets in APIM policy XML or repo. First credential rotation incident exposes them permanently in history.
• Public backend even with APIM in front. Anyone who finds the backend URL bypasses the gateway. Use Private Endpoints / VNet integration.
• No API catalog. Shadow APIs are the dominant external API breach pattern. If you cannot list them you cannot secure them.

Example prompts

• Design a secure API on Azure API Management aligned to the OWASP API Security Top 10.
• How do I validate JWTs at the gateway instead of relying on static API keys?
• Configure rate limiting and payload validation to protect a backend API.
• Review my API authentication and authorization design for least privilege.
• What controls cover BOLA and BFLA on Azure API Management?

Microsoft Learn

• API Management security baseline: https://learn.microsoft.com/azure/api-management/security-baseline
• Protect a backend with Entra ID: https://learn.microsoft.com/azure/api-management/api-management-howto-protect-backend-with-aad
• validate-jwt policy: https://learn.microsoft.com/azure/api-management/validate-jwt-policy
• Mitigate OWASP API threats: https://learn.microsoft.com/azure/api-management/mitigate-owasp-api-threats
• Defender for APIs: https://learn.microsoft.com/azure/defender-for-cloud/defender-for-apis-introduction
• APIM landing zone accelerator: https://learn.microsoft.com/azure/cloud-adoption-framework/scenarios/app-platform/api-management/landing-zone-accelerator