| name | api-security-design |
| description | Guidance for designing secure APIs on Azure - authentication, authorization, gateway controls, input validation, rate limiting, secret management, and runtime threat detection - aligned to OWASP API Security Top 10 and Azure API Management. WHEN: API security design, secure API, OWASP API Top 10, API authentication, API gateway security, rate limiting, validate JWT, protect backend API, API Management security policies, secure API architecture, BOLA, BFLA. DO NOT USE for general application security or web app design (use security-architecture / threat-modelling) or for API runtime detection only (use defender-for-apis). |
| license | MIT |
| metadata | {"author":"Microsoft","version":"0.1.0"} |
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
| OWASP API Top 10 risk | Primary control | Where it lives |
|---|
| API1 - BOLA (object-level auth) | Per-object authorization check | Backend code (gateway cannot fully cover) |
| API2 - Broken authentication | OAuth 2.0 / OIDC with Entra ID, validate-jwt | Gateway + Entra |
| API3 - Broken object property auth | Schema validation + response filtering | Backend + gateway |
| API4 - Unrestricted resource consumption | Rate limit, quota, payload size, timeout | Gateway (APIM) |
| API5 - BFLA (function-level auth) | Role/scope check on each operation | Backend code |
| API6 - Unrestricted access to sensitive flows | Step-up auth, anti-abuse rules | Entra + gateway |
| API7 - SSRF | Outbound URL allow-list + egress controls | Backend + network |
| API8 - Security misconfiguration | IaC + APIM policy templates | DevOps + gateway |
| API9 - Improper inventory management | API catalog + lifecycle in APIM | APIM + governance |
| API10 - Unsafe consumption of third-party APIs | Validate upstream responses, timeouts | Backend |
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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).
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
