Give an API tester a machine-readable spec, saved request collections, test accounts for every role, seeded objects with their IDs, a list of hosts and versions in scope, and a named contact. Every item you withhold becomes reconnaissance time you pay for, or a gap in coverage.
Why handover matters
OWASP's reconnaissance guidance for API testing starts with finding documentation. It says to look for OpenAPI definitions, including older versions that may expose deprecated but still-working endpoints, and to ask clients for machine-readable artifacts such as OpenAPI definitions, request collection files and schemas for non-REST APIs like GraphQL. It also warns that documentation may be inaccurate or incomplete and should be verified.
Handing these over does not make the test easier on you. It moves the tester's hours from discovery to depth.
The handover checklist
| Item | Why the tester needs it |
|---|---|
| OpenAPI file or schema, current and previous versions | Defines the operations to test, and points to old ones |
| Request collections | Show real working requests, headers and auth flows |
| Accounts: two ordinary users, a lower role, a higher role | Required for object and function level checks |
| An unauthenticated baseline | To confirm what truly needs login |
| Seeded objects with IDs per account | Lets the tester try one account's IDs as another |
| Hosts, environments and versions in scope | Prevents testing the wrong target, or missing one |
| Rate ceiling and test window | Keeps the test within your limits and cloud policy |
| Known quirks | Nonces, signed requests, one-time tokens, anti-automation |
| Escalation contact | Someone who can pause the test |
Details that save time
Signed or dynamic requests. The same OWASP guidance notes that when fuzzing authenticated APIs you must reproduce the session handling and recompute dynamic fields such as nonces or signatures on every request. If your API does this, tell the tester how, or provide a sample.
Role differences. The guidance says to browse the app with accounts at different privilege levels to expose more functionality. Provide each role with a short note on what it should and should not be able to do. That note is the expected result against which findings are judged.
Environment. Point the tester at a test environment with synthetic data when possible, and make sure integrations such as email and payments hit sandboxes.
What to hold back
Keep real customer data out of the test. Do not hand over production secrets. Create accounts and tokens just for the test, with an expiry date, and revoke them when it ends.
After the test
Ask for the requests and responses behind every finding, so your developers can reproduce them, and for a list of what was not tested. A list of untested operations is as useful as a list of findings.
Worked example: a handover pack for a subscription billing API
A company is preparing a test of its billing API. The tester starts Monday. Here is the pack the team assembles on the Friday before.
Folder contents.
| File | Contents |
|---|---|
| openapi-current.yaml | The spec generated from the latest release |
| openapi-v1.yaml | The spec for the older version still in use by two customers |
| collections/ | Saved request collections for sign-up, upgrade, cancel and invoice download |
| accounts.md | Four test accounts with roles, plus how to obtain tokens, stored as references to the secrets manager and not as plain passwords |
| seed-ids.md | Subscription and invoice IDs for each test account |
| environment.md | Staging hostnames, versions, rate ceiling, test window, sandbox payment details |
| quirks.md | Notes on signed webhooks, one-time download links and the idempotency header |
| contacts.md | Who can pause the test, and who to call if staging is down |
The note on roles. accounts.md has a short table:
| Account | Role | Should be able to |
|---|---|---|
| acme_owner | Owner | Change plan, cancel, view invoices |
| acme_member | Member | View invoices only |
| globex_owner | Owner at a second customer | Same as above, for its own data |
| support_agent | Internal support | View any invoice, cannot change plans |
This table is the expected-results key. When the tester finds that acme_member can cancel, the table says it is a finding. Without it, the tester would have to guess whether that is intended behavior.
The quirks note. Invoice downloads return a one-time link that expires after one use. A scanner that fetches it twice gets an error the second time. The note tells the tester to ignore that behavior or fetch once per run. The idempotency header must be unique per create request, so the tester knows to generate a new value each time. This is the dynamic-field handling the recon guidance mentions.
What the team left out. No production data. No real card numbers, only sandbox values. No shared admin credentials. Test accounts expire in two weeks and will be disabled afterward.
How the tester uses it
On Monday morning the tester imports both specs, loads the collections, and signs in as the four accounts. The reconnaissance that would have taken a day is done by lunch. The tester compares the specs with traffic captured from the web app and finds a route that is in neither spec: an invoice export used by the finance team. That route becomes a priority target, found only because the time was freed up.
After the handover
Keep the pack. Next quarter, update the specs and seeds and hand the same folder to the next tester or to your own CI job. Over time the pack becomes the definition of how your API is tested.
Common mistakes in a handover
A handover goes wrong in a few repeatable ways, and each one costs the tester time.
- A stale spec. If the spec is a year old, the tester will test the API you had, not the one you have. Generate it from the current build, and say when.
- Credentials that do not work. Check each account yourself before the test starts. An expired password on day one wastes a morning.
- Missing roles. If you hand over two accounts but the API has four roles, two thirds of the function level checks cannot happen.
- No seeded data. Accounts with empty histories cannot test object access. Give each account objects of every type.
- Hidden quirks. Signed requests, anti-automation checks and one-time tokens make a scanner look broken. Describe them.
- No escalation path. If the tester sees something alarming, such as real customer data, they need someone to call.
- Moving targets. A deployment in the middle of the test invalidates findings. Agree a freeze for the window.
Run a ten minute dry run before the tester starts: sign in as each account, call one route per role, and read the spec header for its date. Most handover problems appear in that ten minutes.
Try it yourself
Open the demo and imagine importing your own spec and accounts into a run like this one. Note which findings would depend on the accounts you provide.
Click through it at your own pace, or open it full screen.
Quick check
Is an OpenAPI file enough on its own?
Rarely. It shows operations, but not credentials, roles, object IDs or quirks. Without accounts the tester cannot check authorization.
Should the tester be told about old API versions?
Yes. Old versions are a common place for forgotten endpoints, and the OWASP guidance specifically points at older specs.
Should the tester get production access to speed things up?
No. Use a test environment with synthetic data. If production testing is needed, scope it narrowly, with approval, and use accounts and objects created for the purpose.
Sources
Last reviewed: 19 October 2026.
