How to Scope an API Penetration Test: What to Decide and What to Prepare

Picture the scoping call. The provider asks how many endpoints are in scope, and you open the API documentation and read out the count. It’s a reasonable thing to do, and it’s also where a scope can start to go wrong.

In one engagement, the client documented 84 API endpoints; we found 121 (it’s in the published case study). The documents described 84 endpoints. The system had 121. A scope written from the documents alone describes the smaller system, so the question for you is where the other endpoints would come from.

This article is how we’d put a scope together if we were on your side of the table. One question runs through it: who is allowed to ask for what? An API test is mostly the work of checking the answers, and everything below is a way of writing them down so a tester can check them.

Where the other endpoints come from

Start with the documentation, then set it beside what your gateway or logs show being called, and beside what the code exposes. Wherever the lists disagree, you’ve found scope you didn’t know you had.

You won’t always close the gap before testing starts, and you don’t need to. What you do need is a decision about what happens when a tester finds something that isn’t on your list. Either it’s in scope automatically, or it comes back to you first for a yes. Pick one and put it in writing, because otherwise the first surprise becomes a negotiation in the middle of the test.

The worksheet

Here is the part to copy. Fill in one row per API, or per group of endpoints that behave the same way. The last column is yours to decide; the provider shouldn’t have to guess it.

API and version	Who calls it	How callers prove who they are	What it can move or reveal	In scope?
Example: Payments v2	Our mobile app, two partners	Access token; partners also sign each request	Moves money between accounts	Yes
Example: Statements v1	Our web app only	Session token	Shows account history	Yes, and check whether v1 is still reachable

The “what it can move or reveal” column tells the tester where to spend the days. An endpoint that returns branch addresses and one that changes a beneficiary don’t deserve the same hours, and a path name alone won’t tell anyone which is which.

The second half of the worksheet is about people.

Role	What it is allowed to do	What it must never be able to do
Customer	View and move own money	See or touch another customer’s account
Support agent	View a customer’s record	Change a beneficiary or move money
Partner	Submit payments on behalf of its users	Read another partner’s traffic
Administrator	Manage users and limits	Approve its own limit increase

Write the “must never” column in plain sentences. A tester can only report that the API let someone cross a line if you’ve told them where the line is.

Roles, and the accounts to match

That’s why the role table matters. It gives the tester the one thing a request alone doesn’t carry: who was supposed to be asking. A scanner rarely can do this for you, because it has no list of who is supposed to be asking.

The role table also decides how many test accounts to prepare. Plan two for every role that touches customer data. With a second account, the tester can try to reach the first account’s records using the second account’s token. Add accounts for the edge cases you care about, such as a suspended user or a closed account.

Have these ready as well, so the first morning goes to testing:

how long tokens last, and how a tester refreshes them during a long session
test data that looks real but isn’t, so no real customer is affected
the address of the environment being tested
one named person who can reset or unlock an account the same day

Partners: what the test covers

If partners call your API, a few decisions are yours. Which partner roles need test credentials? Keep them separate from production keys. Does the test run against a partner’s sandbox, a simulator you operate, or the live connection? And do your contracts require you to tell a partner that testing is about to happen?

Your test covers the connection as you run it: your gateway, your endpoints, your handling of the partner’s calls. The partner’s side is outside the scope unless the written agreement says otherwise, and that agreement needs the partner’s permission.

Production or staging?

There isn’t a right answer, only a trade to make on purpose. A test environment is safer to attack, but if its code, configuration or gateway rules differ from production, a clean result there proves less than it seems to. Production shows you what’s really running, and it carries more risk to the live service.

Two questions go a long way. Does staging run the same code and the same gateway rules as production? And does it talk to real partners or to stand-ins? Wherever the answers differ, write the difference into the scope, so the report can say what the result covers and what it doesn’t.

If any of it runs on production, we agree the safeguards in the rules of engagement before we start, and we pace the work so the live service keeps running. Tell us your blackout dates, month-end processing for example.

Two jobs belong to other projects, and it’s worth saying so now. Load and stress testing is one. A line-by-line review of the code behind the API is the other.

If an auditor will read the result

Say up front which framework the result is for. If the API sits in the cardholder data environment, PCI DSS 4.0 requirement 11.4 asks for penetration testing at least every 12 months and after significant changes, and our guide to PCI DSS 11.4 goes through what that means for scope. We can’t tell you how your auditor will read it; the safest move is to ask them what they expect to see, then write that into the scope.

Bring the worksheet, even half-filled

You don’t need it finished. A worksheet with gaps is a good thing to bring to a scoping call, because the gaps are what the session is for. It’s free and runs 90 minutes. If you’d like an NDA in place before you share anything, say so when you book.

Book a scoping session or request a scoped proposal. To see how we run the testing itself, there’s the API penetration testing page.