API Threat Modeling with OpenAPI: A Worked Example

Choose one business flow

API threat modeling works best when the scope is a specific flow rather than every route at once. Consider POST /transfers, which moves money between accounts. List the actors: an account holder, a support operator, the payment service, and an external settlement provider. Identify assets such as account balances, payment instructions, and identity claims. Define the security outcome: only the authorised holder can submit a transfer within policy limits.

OpenAPI provides methods, parameters, schemas, and declared authentication. Add a simple diagram showing the gateway, service, database, queue, and external provider. Mark where a request crosses from a client to your infrastructure, between workloads, and outside your control. The contract alone does not describe those trust boundaries, so interview the service owner and read deployment configuration as well.

Write misuse cases that can be tested

Ask what goes wrong if a caller changes sourceAccountId to another person's account, resubmits the same idempotency key, changes amount after approval, or floods a pending transfer flow. Ask whether an internal worker trusts a queue message from the wrong producer. Each scenario needs a precondition and an observable result. “BOLA possible” is too vague to give an engineer a test.

For the account-swap scenario, the expected control is server-side ownership checking before a debit. The negative test creates two users and tries to debit the first user's account using the second user's token. For a replay scenario, submit a request twice with the same idempotency key and verify that only one transfer is recorded. These tests connect a threat to evidence.

Use OpenAPI as a review input

Inspect whether the transfer operation documents a security requirement, constrained amount and account fields, 400 and 403 errors, and an idempotency mechanism. A missing declaration is a valuable question, but a complete schema does not prove the implementation enforces it. Conversely, a missing limit in the file may be enforced by a gateway; verify rather than inventing a vulnerability.

APISAST reviews OpenAPI and Swagger files for design signals such as missing security, weak validation constraints, and undocumented errors. It cannot inspect ownership rules, queue consumers, fraud decisions, or settlement responses. Use scanner findings to improve the contract and seed the threat-model workshop. Assign runtime checks to tests that can actually observe the service.

Prioritise with local consequences

Score a scenario using the value of the asset, exposure of the route, prerequisites, and harm to users or operations. A publicly reachable transfer endpoint with a suspected ownership gap needs attention before a low-impact documentation omission. Record assumptions such as “the gateway rejects anonymous calls” and a way to verify them. If the assumption fails, update the priority.

Select controls with clear owners. The API team owns object authorization, the gateway team may own coarse quotas, and the payment team owns settlement validation. A compensating rate limit cannot replace an ownership check. If a risk is accepted temporarily, record who accepted it, for how long, and what evidence would cause reconsideration. Avoid a threat register full of unowned generic statements.

Review external and asynchronous paths

The settlement provider's response is untrusted input. Validate status, identifiers, and amounts before updating internal state. Bound timeouts and retries so a provider outage does not create duplicate charges or exhaust workers. Sign or authenticate callbacks and reject replay. Draw these flows even if the public OpenAPI document stops at the initial POST response.

Follow data into logs and analytics. A transfer error might expose an account number in a trace or send a payment token to a monitoring provider. Define redaction and retention controls, then verify a sample failure path. Threat modeling is not confined to request validation; the response, background job, and operational record can carry the same sensitive data.

Keep the model small and current

Publish a one-page record: diagram, assumptions, top misuse cases, selected controls, owners, and links to tests. Revisit it when the operation gains a new client, new data field, provider, or authentication path. A change to a permission boundary should trigger review even if the URL stays the same.

At release, confirm that each high-priority scenario has a passing negative test or a documented exception. Compare the deployed route inventory with the reviewed contract. The value of the model lies in decisions and verification, not in the number of boxes in a diagram.

Create a threat-to-test table

For the transfer flow, record one row per misuse case. The account-swap row names the actor, source account, expected 403 or equivalent denial, and the negative test fixture. The replay row names the idempotency control and the expected single ledger entry. The oversized amount row names a limit and the expected validation response. Link each row to the implementation owner and test.

Include a column for evidence type. An OpenAPI schema can show a documented bound; a unit test can show validator behaviour; an integration test can show database state; production telemetry can show whether the control is being used. These are different claims. When a reviewer says a threat is mitigated, the table should show which evidence supports that statement and where gaps remain.

Watch for a changed trust boundary

A new mobile client, webhook, or partner can invalidate assumptions made for a first-party browser. Ask who controls the new client, how it obtains a token, and whether it can send requests directly to the service. If a message queue replaces a synchronous call, add producer authentication, replay handling, and dead-letter processing to the model.

Schedule a short review when a boundary changes rather than waiting for an annual audit. The owner should update the diagram and run the affected negative tests before release. This keeps the model proportionate: only the part of the system with a changed assumption needs a deeper new analysis.

Continue the work

Use these guides to put the checks into your API review process:

• Inventory shadow and zombie APIs
• Use OWASP risks in contract review
• Review the OpenAPI specification

Primary reference: OWASP Threat Modeling Cheat Sheet.

APISAST reviews OpenAPI and Swagger contracts for documented design signals. Confirm authorization, enforcement, performance, and abuse controls against a running service.