API Threat Modeling: Secure Design Before Code

An API can pass every functional test and still expose another customer's records with a single changed identifier. That is why API threat modeling belongs before implementation details harden into architecture. It gives developers and security engineers a repeatable way to identify how an attacker can misuse an endpoint, cross a trust boundary, bypass authorization, or turn an integration into a data-exfiltration path.

For an Application Security Engineer, the objective is not to produce a diagram that disappears into a ticketing system. The objective is to turn API design decisions into testable security requirements that engineering teams can implement, review, and verify.

Why APIs require focused threat modeling

APIs concentrate valuable capabilities behind predictable interfaces: account management, payments, data exports, administrative actions, and partner integrations. Their security often depends less on whether authentication exists and more on whether every request is authorized correctly in its specific business context.

A common failure illustrates the distinction. An endpoint such as GET /accounts/{accountId}/invoices/{invoiceId} may require a valid access token. Authentication succeeds, but a user can substitute a different invoiceId and retrieve another account's invoice because the application never verifies the relationship among the user, account, and invoice. This is broken object level authorization, and it is a design and implementation problem that threat modeling should expose early.

Traditional network-focused reviews can miss these conditions because the API is reachable exactly as intended. The threat exists in the object relationships, workflow states, and authorization rules behind the route. APIs also evolve quickly through new versions, mobile clients, microservices, third-party consumers, and asynchronous event processing. A one-time security review is not enough.

API threat modeling begins with the real system

Start with a concrete scope. Select an API domain, a high-risk workflow, or a change set that introduces new data access or privileged actions. Trying to model an entire platform in one workshop usually produces vague findings. Modeling the customer billing API, password reset flow, or partner data-export integration produces decisions a team can act on.

Document the API's assets first. Include the obvious items, such as personally identifiable information, payment data, credentials, session tokens, and API keys. Also identify assets that are easy to overlook: authorization decisions, account balances, rate-limit capacity, audit records, webhook signing secrets, internal service identities, and message queues.

Then create a data flow diagram that reflects how the system actually works. Show clients, API gateways, identity providers, application services, databases, caches, third-party APIs, queues, and administrative interfaces. Label data flows with protocol, authentication mechanism, and the category of data being transferred. A simple, accurate diagram is more valuable than a detailed but fictional architecture drawing.

Trust boundaries are central. A mobile app is not a trusted execution environment merely because it uses an access token. A request arriving through an API gateway may have passed authentication, but the downstream service still needs to make an authorization decision. A signed webhook may establish origin authenticity, but it does not guarantee that the payload is fresh, valid for the current business state, or safe to process repeatedly.

Questions that expose design risk

Once the flow is visible, ask questions tied to each endpoint and state transition. Who can invoke this operation? What object, tenant, role, or relationship determines access? Can the caller influence identifiers, filters, sort fields, redirect URLs, or downstream destinations? What happens if requests are replayed, parallelized, delayed, or sent out of sequence?

These questions move the discussion beyond generic statements such as "use encryption" or "validate input." TLS and input validation matter, but they do not resolve a design in which a low-privilege user can approve a refund, enumerate records, or call an internal administrative operation through an exposed route.

Model abuse cases, not only technical weaknesses

A useful API threat model combines a structured method such as STRIDE with business-logic abuse cases. STRIDE helps teams consider spoofing, tampering, repudiation, information disclosure, denial of service, and elevation of privilege. For APIs, the most serious findings frequently emerge when those categories are applied to objects and workflows rather than only to infrastructure.

Consider a funds-transfer API. The intended flow might be create transfer, verify recipient, approve transfer, and submit for processing. An attacker might skip verification, replay approval calls, alter the recipient after approval, race two requests against a balance check, or use an endpoint intended for one tenant against another. None of these scenarios requires a novel exploit. They require the attacker to understand the API's valid operations and invoke them in an invalid sequence.

For each high-value flow, write abuse cases in plain language and map them to the affected endpoint, data, and control. Four patterns deserve consistent attention:

• Object-level authorization failures, where a caller accesses or changes a record they do not own.
• Function-level authorization failures, where a lower-privilege role invokes an administrative or sensitive action.
• Excessive data exposure, where the API returns fields the client does not need and relies on the client to hide them.
• Resource-consumption and automation abuse, where pagination, search, file processing, verification codes, or expensive queries can be exploited at scale.

This approach also catches risks unique to API styles. GraphQL can expose authorization gaps through nested queries, aliases, introspection, or query depth and complexity. REST APIs often present risks through predictable identifiers, mass assignment, overly permissive filters, and inconsistent versioning. Event-driven APIs need attention to message provenance, schema validation, replay resistance, idempotency, and consumer authorization.

Turn threats into engineering requirements

A threat model becomes useful when each material threat has a clear disposition. Some threats need a preventive control, such as a centralized authorization check. Others require detection, such as alerts for abnormal export volume. Some risks can be accepted when the impact is low and the rationale is documented. What matters is that the decision has an owner and can be verified.

Authorization requirements should be specific. "Require authorization" is not enough. A better requirement states that the service must verify the authenticated principal is authorized to access the requested invoice within the tenant identified by the route and that the tenant context cannot be supplied solely by an untrusted client field. That requirement can be translated into code, unit tests, integration tests, and secure code-review checks.

Controls should match the threat. For bulk export abuse, role-based access alone may be insufficient. The design may need scoped permissions, export size limits, asynchronous processing, approval for sensitive datasets, rate limits, audit logging, and anomaly detection. The appropriate combination depends on the data sensitivity, expected usage volume, and operational cost of false positives.

Do not treat the API gateway as the complete security boundary. Gateways are effective for token validation, schema enforcement, rate limiting, and traffic controls. They generally cannot evaluate every business relationship in a downstream service. The service that owns the data often needs to enforce object-level and function-level authorization close to the business logic.

Validate the model through testing

Threat modeling should feed directly into the secure development lifecycle. During design review, verify that proposed controls exist in the API contract and architecture. During implementation, use secure code review to inspect authorization placement, input handling, error behavior, logging, and outbound request construction.

SAST can identify supporting implementation weaknesses, including unsafe deserialization, injection sinks, hardcoded secrets, and missing security checks when rules are available. DAST and API security testing can exercise routes with altered identifiers, malformed payloads, missing claims, unexpected methods, excessive request volume, and authorization tokens from different roles or tenants. Neither tool category replaces a threat model, because automated testing cannot reliably infer every business rule. The model tells testers what relationships and state transitions must be challenged.

Build negative tests from the abuse cases. Test that a user cannot read another tenant's object, that an approver cannot modify an already approved recipient, that a replayed webhook does not create a duplicate action, and that an API response omits sensitive fields for lower-privilege consumers. These tests are valuable regression controls as services and authorization policies change.

Make threat modeling part of delivery

The best time to model an API is when the team can still change the design cheaply: during architecture review, API contract definition, or backlog refinement for a high-risk feature. For established services, start with the endpoints that handle sensitive data, privileged functions, cross-tenant access, financial actions, or external integrations.

Keep the output disciplined: a current data flow diagram, prioritized threats, explicit control requirements, owners, and validation evidence. Revisit it when authentication changes, new consumers are added, data classifications change, or a workflow gains a privileged state transition. Threat models age with the system.

Developing this habit is a core AppSec engineering skill. At appsec.training, threat modeling is treated alongside secure code review, SAST, and DAST because effective application security depends on connecting design risk to implementation and testing. Start with one meaningful API workflow, make its authorization rules explicit, and give the team security tests that prove those rules hold under adversarial use.