API Penetration Testing: Process, Types, Tools and a Worked Example

API penetration testing is an authorized, scoped attempt to find and prove exploitable weaknesses in an API: its endpoints, methods, parameters, identities and data. It sits inside penetration testing and inside an API security testing program. Unlike a scan, it starts with recon, chains real requests against authentication and authorization, exploits only as far as the written rules allow, and ends with a report, fixes and a retest.

An API pen test at a glance.

What is API penetration testing?

An API penetration test is an authorized attempt to discover and prove exploitable weaknesses in a specific API. The word carrying the weight is prove. A tester does not report that an endpoint looks risky. They send the request, keep the response, and show what an attacker reaches.

Penetration testing is the broad practice: an authorized simulated attack on a system, a network or an application. API security testing is the ongoing program around your endpoints, covering scanning, automated tests and monitoring. An API pen test is one scoped engagement inside that program.

The API layer changes the work in one way. A tester cannot rely on a user interface to reveal the surface, so it has to be assembled from schemas, documentation, client traffic and discovery. OWASP's Web Security Testing Guide gives API testing its own chapter, and its topics are API reconnaissance, broken object level authorization, excessive data exposure, broken function level authorization and GraphQL.

The same guide names the rest of the ground a tester covers in a web application: information gathering, configuration and deployment management, identity management, authentication, authorization, session management, input validation, error handling, weak cryptography, business logic and client-side testing. An API engagement borrows from those chapters. The API chapter is the one that deals with the part unique to APIs, which is that the surface has to be found before anything can be tested.

Scope and rules of engagement for an API pen test

Testing without written permission is not a pen test. Sign the rules of engagement first.

• Authorization. Which organization grants permission, to which named tester, and who can withdraw it.

• Targets. Exact domains, hosts, IP ranges, environments, API versions, endpoints, methods and third-party services. Anything unlisted is out of scope.

• Inputs. Whether OpenAPI or Swagger files, source code or architecture notes are supplied.

• Identities. Test accounts, roles, tenants and seed data. Cross-tenant object tests need at least two accounts in two tenants; function-level tests need a low-privilege role beside a privileged one.

• Techniques. Denial of service, destructive calls, social engineering and real customer data are the four to settle in writing. PTES says to settle denial of service testing before the engagement begins.

• Limits and timing. Request rate, permitted hours, dates, change freezes, and a stop contact who answers a phone.

• Third parties. A customer cannot grant permission over a provider's systems. PTES is explicit, so separate permission is needed.

• Evidence. How proof is captured and redacted, where it is stored, when it is deleted.

• Outcomes. Success criteria, reporting route, remediation owner and retest window.

NIST SP 800-115 is the public reference for planning and conducting technical security tests, analyzing findings and developing mitigation strategies. Name it in the report's methodology section. One caveat: this is operational guidance, not legal advice. Local law, contracts and your counsel decide what is permitted.

The API penetration testing process

One process, seven phases. The Penetration Testing Execution Standard names them Pre-engagement Interactions, Intelligence Gathering, Threat Modeling, Vulnerability Analysis, Exploitation, Post Exploitation and Reporting. What matters is what each means for an API.

Two phases set up everything after them. Intelligence gathering decides what gets tested at all, so a missed version is a surface nobody looked at. Threat modeling decides the order, because the time is fixed and the surface is not.

The phase names are PTES's. The mapping to an API is this page's, and so is the order in which the outputs matter: an inventory you trust, a plan you can defend, then findings with the requests attached. NIST SP 800-115 describes its own purpose in the same shape, as helping an organization plan and conduct technical security tests, analyse what comes back and develop mitigations. Plan, test, analyse, fix. Name the standard you followed in the report's methodology section, so a reader can tell a structured engagement from an unplanned one.

API recon: documentation, schemas and endpoint discovery

Recon is where an API test diverges most from a web application test. A browser walks you around a web app. An API answers only what you already know to ask for, so the surface is built from several sources.

• Machine-readable schemas. OpenAPI and Swagger documents list paths, methods, parameters, types and responses. Fetch them from the usual locations and from wherever the client loads them.

• Human-readable documentation. Portals, changelogs and support articles name endpoints the schema left out, and deprecated versions still answering.

• Client traffic. Proxy the web front end and the mobile app. PortSwigger notes that APIs not fully used by the front end still need testing, so what you capture is a floor.

• Error messages. A verbose validation error can name parameters, types and routes that appear in no document.

• Old and shadow versions. A retired /v1 can still answer beside a documented /v2, and it may be running code that never got the check the new version has. An API inventory makes those visible.

Treat the schema as a starting inventory, not proof it is complete. Good API documentation is written to help developers, not to enumerate what an attacker can reach.

Discovery differs by API style. GraphQL exposes its type system through introspection wherever that feature is left enabled, handing a black box tester the query and mutation list. SOAP publishes a WSDL describing its operations. REST has no built-in discovery mechanism, so REST API testing leans on schema files, traffic and path enumeration.

Test methods, content types and hidden parameters

Once the paths are known, the variations start. A path is not one target. It is one target per combination of method, media type, identity and parameters.

• Vary the method. Send GET, POST, PUT, PATCH, DELETE, OPTIONS and HEAD at the same path. A framework can register more verbs than the documentation admits, and an authorization check can be attached to one verb and not the others. Both are conditions to test, not assumptions.

• Vary the media type. Resend the same body as JSON, form encoding and XML. A parser that runs on one content type can skip validation the other applies.

• Read the differences. Status codes, timing, error wording and response length separate a path that exists from one that does not, even when both refuse you.

• Fuzz paths and parameter names. Wordlists find segments and fields nobody documented. Here the agreed request rate stops being paperwork, because a high-rate fuzzing run can overload a target by accident.

• Test undocumented fields. Add fields the schema does not mention, such as a role or an owner ID, and see whether the server binds them to the object. That is mass assignment: the server binds fields from a structured body straight onto its own object, so a field no schema mentions can still land on the record.

Malformed values, wrong types and boundary inputs belong in the same pass. API fuzz testing covers how to generate them.

Authentication and authorization: BOLA and BFLA

Keep the two apart, because the tests differ. Authentication proves who the caller is. Authorization decides what that caller may do. An API can get API authentication perfectly right, issue a valid token to the right person, and still hand that person another customer's records.

Authorization testing needs a matrix with six columns: user, role, tenant, object, endpoint, method. Fill it with at least two accounts in two tenants and one low-privilege role, then walk the cells. Every cell is a request with a known correct answer, which makes the result evidence rather than an opinion.

BOLA is API1:2023 Broken Object Level Authorization. Object level authorization is the code-level check that a user may act on the object they named. OWASP's rule: every endpoint that receives an object ID and acts on it should validate that the logged-in user has permission for that action on that object. The test holds the identity fixed and changes the object ID to one owned by somebody else. Expect a refusal.

BFLA is API5:2023 Broken Function Level Authorization. Here the tester reaches a function outside their role rather than an object outside their ownership. OWASP gives two cases to hunt: a regular user reaching an administrative endpoint, and a user changing GET to DELETE to reach a sensitive action. Our guide to broken function level authorization works through the matrix.

Limit the proof. One record across a tenant boundary proves it is missing. Enumerating the table turns a test into an incident.

What an API pen test should cover: the OWASP API Security Top 10

The 2023 edition is the coverage list, one line each on what the tester varies. The category names are OWASP's; the test line beside each is this page's, not OWASP text. Our OWASP API Security Top 10 guide goes deeper, and the API security testing hub covers the program around it.

• API1:2023 Broken Object Level Authorization. Hold the identity, change the object ID, expect a refusal.

• API2:2023 Broken Authentication. Attack token issue, expiry, signature, refresh and reset flows.

• API3:2023 Broken Object Property Level Authorization. Read fields you should not see, write fields you should not set.

• API4:2023 Unrestricted Resource Consumption. Probe rate limits, page sizes and anything costing money per call.

• API5:2023 Broken Function Level Authorization. Send a low-privilege identity at privileged functions and other verbs.

• API6:2023 Unrestricted Access to Sensitive Business Flows. Automate a flow the business assumes a human performs.

• API7:2023 Server Side Request Forgery. Feed URLs into any parameter the server fetches, and watch where it goes.

• API8:2023 Security Misconfiguration. Check headers, CORS, TLS, verbose errors, debug routes, default credentials.

• API9:2023 Improper Inventory Management. Hunt old versions, staging hosts and endpoints serving production data.

• API10:2023 Unsafe Consumption of APIs. Examine what your API trusts from the third-party APIs it calls.

Black, gray and white box API testing, and coverage versus depth

Access model is what the tester holds before the first request.

• Black box. A base URL and nothing else. It mirrors an outside attacker, and an undocumented endpoint found anyway is a real finding. The blind spot is time: hours enumerating are hours not spent on logic.

• Gray box. Documentation, a schema and test accounts in more than one role. Useful whenever authorization is the target, because those tests cannot run without credentials in more than one role.

• White box. Source code, configuration and infrastructure access on top. It reaches logic that outside requests may not provoke. Its blind spot is realism: knowing where a check lives makes it harder to notice a path that skips it.

Coverage-based versus depth-based is a different decision, and the two get confused. Coverage-based means testing more of the surface with less time in each place. Depth-based means going after fewer targets harder. That is breadth of targets, not what the tester knows, so a black box test can be either.

The access model does not change the API-specific work. The same path still behaves differently by method, media type, identity, role, tenant and object ID, so one happy-path request is not coverage in any of the three modes. APIs also hand resource consumption and business flows straight to automation, which is why rate limits, page sizes, expensive operations and multi-step flows stay on the list, inside the agreed safety limits. Those two are API4 and API6.

Worked example: from recon to a BOLA proof

Run this only against a lab, a staging API or another target covered by your written authorization. It needs curl, jq, two synthetic users, and one synthetic order owned by user B.

Nothing here runs as printed. api.example.test resolves nowhere and the three values are placeholders. Before running it, set BASE_URL to the host in your scope, put user A's test token in USER_A_TOKEN, create the order as user B and put its ID in USER_B_ORDER_ID, and confirm the OpenAPI path your API actually serves.

The first command lists documented methods and paths from the OpenAPI document, so the test set is a list rather than a guess. The second sends user A's token to an order belonging to user B: a valid identity, somebody else's object ID, which is the BOLA condition exactly.

BASE_URL="https://api.example.test"
USER_A_TOKEN="replace-with-user-a-test-token"
USER_B_ORDER_ID="replace-with-user-b-test-order-id"

# Recon: list documented methods and paths.
curl -sS "$BASE_URL/openapi.json" |
  jq -r '.paths | to_entries[] | .key as $path | .value | to_entries[] | select(.key | test("^(get|post|put|patch|delete|options|head)$")) | "\(.key | ascii_upcase) \($path)"'

# Authorization test: user A requests an order owned by user B.
curl -i -sS \
  -H "Authorization: Bearer $USER_A_TOKEN" \
  "$BASE_URL/api/orders/$USER_B_ORDER_ID"

Reading the result. A secure API refuses the second request, commonly with 403, or with a deliberately non-revealing 404 that declines to confirm the record exists. A 200 carrying user B's order is evidence of possible BOLA.

Write down which one you got. A refusal does not say which check produced it, so read the server log for that request before you name the control in the finding. A non-revealing 404 is usually a deliberate choice, worth confirming with the team rather than filing as a missing record.

The evidence limit. One record is the proof. Save the request and response, note the identity and role, redact the personal data, and stop. Do not iterate the ID range to count exposed records. The impact statement can describe that range without your having pulled it.

The fix and the retest. Resolve the owner from the authenticated session and scope the query to that identity, rather than trusting the ID in the path. OWASP goes further and says to write tests that evaluate the authorization mechanism, and not to deploy changes that make those tests fail. Replay the same two commands after the fix ships. Written down, that replay is already the regression test.

API penetration testing tools

Seven tools, each with a distinct job in an API test.

Qodex is the half that runs between engagements, re-testing findings a person already confirmed. The other six split into three jobs. Burp Suite, ZAP and Postman handle the request itself: intercept, edit, replay, and hold the identities you replay as. ffuf and Kiterunner find what nobody gave you, paths and parameter names, at a request rate the scope has already fixed. Nuclei turns a condition you have already confirmed into a check that runs again. None of them knows your authorization rules, so none can tell you a 200 was wrong. That judgement stays with the tester.

For the wider market, see our comparison of API security testing tools.

API penetration test versus vulnerability scan

Both are useful, and they answer different questions. A scanner checks signatures and templates. A tester chains requests across roles, object IDs, methods and business flows to show what an attacker actually reaches.

The row that decides between them is business logic. A template can report a missing header or an old version. It cannot know that user A should never see order 42, because that rule lives in your data and not in a signature.

Teams run both. The scan keeps the obvious from piling up. The test finds what only a person chaining requests finds.

Reporting, remediation and continuous retesting

An API finding is only as useful as the record behind it. Each should carry the endpoint and method, the identity and role that sent the request, and the request and response as evidence. Then the business impact in plain terms, the fix, a named owner and the retest result. That lets an engineer reproduce it without a meeting.

Then the finding stops being a one-time event. A confirmed BOLA becomes a two-user test that swaps the object ID on every release. A confirmed BFLA becomes a role-and-method matrix that sends a low-privilege identity at administrative functions and expects a refusal. A mass-assignment finding becomes a negative request in the API suite.

That handoff is what Qodex automates: the finding the engagement proved becomes a check that runs while no tester is engaged. It runs attack chains against your preview on every pull request, with two real accounts in two organizations, so the cross-tenant read the report described is attempted again rather than assumed. The assertions are inverted on purpose, so a pass means the attack was blocked and relaxing one cannot turn a failure green. It reports the failing request and response. The production half of the same loop is API security monitoring.

The boundary matters. This does not replace a penetration test signed by a human, and it produces no certificate or attestation for an auditor. It does not replace the human-led parts either: the legal scoping, the judgement in threat modeling, and exploitation a person holds to agreed limits. It covers the other eleven months. Run API security tests with Qodex.

Frequently Asked Questions

What does API penetration testing mean?

An authorized, scoped attempt to find and prove exploitable weaknesses in an API. The tester maps endpoints, methods and parameters, then sends real requests as real identities to see what the API allows. Permission is written down first, and the result is evidence rather than an opinion.

How is an API penetration test different from a vulnerability scan?

A scan matches signatures and templates automatically. A pen test chains requests across roles, object IDs, methods and business flows to prove what an attacker gets. The scan produces candidates, some false. The test produces a request, a response and an impact.

What are black, gray and white box API pen tests?

Black box gives the tester a base URL and nothing else, mirroring an outside attacker. Gray box adds documentation, a schema and test accounts in several roles, the usual choice because authorization needs credentials. White box adds source code and infrastructure access.

How do you scope and legally authorize an API penetration test?

Get written rules of engagement first. Name who grants permission and to whom, the hosts, versions and environments, the test identities and roles, the allowed and prohibited techniques, the request rate, the stop contact and the retest window. Third-party systems need their owner's separate permission.

How do testers find undocumented API endpoints and parameters?

By combining sources: OpenAPI and Swagger files, developer documentation, proxied traffic from web and mobile clients, verbose error messages, and old versions still answering. Route wordlists and parameter fuzzing fill the gaps, at a rate the scope allows. Treat the schema as a starting inventory, not proof that the list is complete.

How do you test BOLA and BFLA safely?

Use synthetic accounts and data in an authorized environment. For BOLA, keep one identity and request an object owned by another test user, expecting a refusal. For BFLA, send a low-privilege identity at privileged functions and other verbs. Stop at one record.

Which tools are used for API penetration testing?

Burp Suite and OWASP ZAP for intercepting and replaying requests. Postman for collections, test identities and assertions. ffuf and Kiterunner for path and parameter discovery. Nuclei for turning a confirmed weakness into a repeatable check. No tool decides whether an action breaks your authorization rules, so a finding still needs a person to confirm it.

How often should an API be penetration tested, and what belongs in the report?

There is no universal number. Test after material change, on a cadence set by risk and contract, with a retest after every fix. The report carries the endpoint and method, the identity and role, the evidence, the impact, the fix and its owner. A pen test validates scoped technical weaknesses, red teaming simulates an adversary across people and process, and purple teaming puts both sides together to improve detection.

Want confirmed API findings to stay fixed? Run API security tests with Qodex.