API Penetration Testing Guide: Scope, BOLA and Reports

Most serious API weaknesses are authorisation flaws that scanners cannot see, so an API penetration test is only as good as its scope, its test accounts and the tester's understanding of who should be allowed to do what. APIs carry the data and business logic that web and mobile front ends only display, and partner integrations, machine clients and AI agents call them directly. This guide is for buyers, programme owners and defenders who commission or run API tests. It covers how to scope an API test, what coverage to expect against the OWASP API Security Top 10 2023, how to handle test accounts and API keys as non-human identities, provider and hosting rules, safety, and how to turn findings into fixes. It deliberately contains no exploit steps, tool commands or payloads.

Key takeaways

Authorisation is the core of the test. Broken object level authorisation (API1:2023) and broken function level authorisation (API5:2023) need a tester with several accounts at different privilege levels, not a scanner with one token.
Scope from an inventory, not a URL. Give testers the API descriptions, versions, environments and consumers, because forgotten versions and hosts (API9:2023) are where tests most often find the worst issues.
Test credentials are non-human identities. Issue dedicated test accounts and API keys, scope them to the engagement, record them, and revoke them on the last day.
Safety rules belong in the contract. Rate limits, production data handling, business flow side effects and cloud provider rules on flooding must be agreed before testing starts.
A good report proves impact and gives a retest path. Each finding should name the endpoint, the role pair or object relationship involved, the business impact and a fix that can be verified.

What makes API penetration testing different

A web application test explores what a browser user can reach. An API test works from the interface contract itself: every operation, parameter, object identifier and role the API accepts, whether or not a front end ever calls it. Three things follow from that.

Headless coverage: many APIs have no user interface at all (partner APIs, internal microservices, machine to machine integrations, mobile back ends, agent tool endpoints). "Headless API pentesting" simply means testing from the API description and real client traffic rather than from screens.
Logic over signatures: OWASP notes that BOLA is widespread because the server relies on object IDs sent by the client to decide which object to return, and that the server response alone shows whether the attempt worked. That makes these flaws easy for attackers and invisible to signature tools that do not know who owns which object.
Multiple API styles: REST, GraphQL, gRPC and WebSocket APIs fail in different ways. GraphQL, for example, does not enforce permissions by default, so access must be checked on every resolver, and deeply nested queries can exhaust resources (OWASP WSTG-APIT-01).

For the broader testing programme see the Penetration Testing Guide; for browser-facing applications see the Web Application Security Testing Guide.

Scoping an API test

The NCSC advises that scoping involve risk owners, technical staff who know the target and the testing team, and that it produce a plan covering technical boundaries, timeframe and effort, scenarios, special requirements and reporting formats. For APIs, add the items below. The Penetration Test Scoping Checklist covers the general items.

Scoping input	What to provide	Why it matters
API descriptions	Current OpenAPI, GraphQL schema or protobuf definitions, plus any undocumented endpoints known to the team	Lets testers cover every operation, not only those the front end calls
Versions and hosts	All live versions (v1, v2, beta), staging and partner hosts, regional deployments	Old versions often share the production database with weaker controls (API9:2023)
Role and tenant model	Roles, tenants, sub-users, delegated admins, service clients and their intended permissions	The tester needs a written "who may do what" to judge authorisation results
Test accounts and keys	At least two accounts per role, in at least two tenants, plus machine credentials	WSTG-ATHZ-04 recommends at least two (often more) users, including different privileges
Authentication flows	OAuth grant types, token lifetimes, API key scheme, mTLS, identity provider used	Defines what broken authentication (API2:2023) tests apply
Sensitive business flows	Purchase, booking, transfer, sign-up, password reset, voucher or referral flows	API6:2023 abuse is business specific and must be named to be tested
Third-party APIs consumed	Upstream APIs and webhooks the service trusts	Unsafe consumption (API10:2023) is tested on your side, never against the third party without its consent
Environment and data	Production, pre-production or dedicated test tenant; synthetic or real data	Drives safety rules and what evidence testers may keep

Choosing the test approach

Open-box (full information): descriptions, source access or architecture diagrams, and a briefing from developers. Best value for finding authorisation flaws in a fixed number of days.
Closed-box: no documentation, only a base URL or a client application. Better models an external attacker and tests whether discovery is possible, but the NCSC notes it may miss issues within the time allowed.
Grey-box (most common): descriptions and test accounts, no source. A sensible default for most organisations.

Test coverage against the OWASP API Security Top 10 2023

Use the OWASP API Security Top 10 2023 as a coverage map, not as the whole test. Ask the provider to state in the proposal and the report which categories were tested, how, and which were out of scope.

Category	What the tester examines	Needs from you	Typical evidence
API1 Broken Object Level Authorization	Whether one user can read or change another user's or tenant's objects through IDs in paths, queries, headers or bodies	Two or more accounts per role and tenant, objects owned by each	Request by account A returning object owned by account B
API2 Broken Authentication	Token validation, credential reset, brute force protection, weak key schemes, unprotected authentication endpoints	Description of auth flows, lockout policy	Accepted invalid or expired token; missing throttling on credential endpoints
API3 Broken Object Property Level Authorization	Excessive data in responses and properties a caller can set but should not (mass assignment)	Field level permission rules	Response containing hidden fields; privileged property accepted on update
API4 Unrestricted Resource Consumption	Missing limits on rate, payload size, page size, query complexity and costly downstream calls	Agreed safe rate ceilings	Limit absent or inconsistent, shown at low volume
API5 Broken Function Level Authorization	Whether regular users reach admin functions or other roles' operations	Role matrix, admin and non-admin accounts	Non-admin account completing an admin operation
API6 Unrestricted Access to Sensitive Business Flows	Whether flows can be automated at a scale that harms the business	Named flows and business rules	Flow completed repeatedly without anti-automation controls
API7 Server Side Request Forgery	Parameters that make the server fetch a URL	Agreement on internal targets that are out of bounds	Server fetching a tester-controlled location
API8 Security Misconfiguration	TLS, CORS, verbose errors, unnecessary methods, missing security headers	Environment details	Configuration evidence
API9 Improper Inventory Management	Old versions, undocumented hosts, debug endpoints	Known inventory to compare against	Endpoints found that are not in the inventory
API10 Unsafe Consumption of APIs	How the API trusts data from upstream services and webhooks	List of consumed APIs; test doubles where possible	Unvalidated upstream data accepted

OWASP's guidance for API5 is to analyse the authorisation mechanism with the user hierarchy, roles and groups in mind and ask whether a regular user can reach administrative endpoints. That analysis only works if the tester receives the role model during scoping. For defensive detail on each risk see the Top 10 API Security Risks and the API Security Guide.

BOLA and BFLA as test areas

Authorisation testing deserves a defined share of the effort. A practical way to brief a provider is to ask for an authorisation matrix: every operation down one side, every role and tenant across the top, and an expected result in each cell. The tester then reports where the actual result differs.

Object level (BOLA): covers horizontal access between users of the same role and cross-tenant access. Include indirect identifiers such as file names, order numbers and GraphQL node IDs, not only numeric IDs. OWASP notes object IDs may be sequential integers, UUIDs or strings, so random IDs do not replace an ownership check.
Property level (BOPLA): covers fields a caller should not see or set, for example role, price, owner or approval status.
Function level (BFLA): covers vertical access to admin or other role operations, including alternative HTTP methods on the same path and internal endpoints exposed through a gateway.
Machine clients: include service clients and partner keys in the matrix. A partner key scoped to read orders should not create refunds.

OWASP ASVS 5.0 gives matching verification requirements that developers can test against between penetration tests: V8.2.1 (function level access restricted to consumers with explicit permissions), V8.2.2 (data specific access, to mitigate IDOR and BOLA) and V8.2.3 (field level access, to mitigate BOPLA). Writing automated tests for these in the build pipeline is the most effective way to stop the same class of finding returning in every test.

Test accounts and API keys as non-human identities

An API test needs credentials, and those credentials are often more powerful and longer lived than intended. Treat them as non-human identities with an owner, a scope and an end date.

Stage	Control	Evidence to keep
Issue	Create dedicated, clearly named accounts and keys per engagement; never reuse employee accounts or shared keys	List of accounts, keys, roles and tenants issued
Scope	Least privilege for each test role; restrict keys to in-scope APIs and environments; IP allow list for the tester where practical	Scope statement tied to each credential
Deliver	Hand over through a secrets manager or one-time link, never in email or tickets	Delivery record
Monitor	Tag test identities so security monitoring can separate test traffic without suppressing alerts	Alert and log samples
Revoke	Disable accounts, revoke keys, refresh tokens and OAuth grants on the last day; rotate any production secret the tester saw	Revocation confirmation in the closure report

Testers also find credentials: keys in client bundles, tokens in responses and secrets in old versions. Agree in advance that any discovered secret is reported immediately, used only to show it is valid where authorised, and rotated by you. The Red Hat Consulting GitLab breach shows why: engagement reports held by a supplier reportedly contained authentication tokens and connection strings for customer environments. Keep live secrets out of reports, and ask the provider how it stores and destroys engagement data. See the API Key Management Guide and the Machine-to-Machine OAuth (Client Credentials) Guide.

Provider rules, safety and rules of engagement

Cloud hosting rules: if the API runs in a public cloud, the cloud provider's policy applies in addition to your contract. AWS lists Amazon API Gateway and AWS AppSync among services that may be tested without prior approval, but prohibits request flooding, including login and API request flooding. Microsoft's rules encourage DAST and fuzzing of web applications and APIs while prohibiting network-intensive fuzzing and any denial of service. See the Cloud Penetration Testing Guide.
Third-party APIs: you can authorise testing of your own API, not of a payment, identity or SaaS provider it calls. Use sandboxes or test doubles, or obtain the third party's written consent.
Rate ceilings: agree a maximum request rate per endpoint and a stop condition. Resource consumption findings (API4:2023) should be shown at low volume, not by degrading the service.
Business side effects: write operations can send emails, charge cards, trigger fulfilment or notify regulators. Name these operations, provide test merchants or suppressed notifications, or exclude them.
Production data: if testing touches real personal data, define what the tester may view, the minimum evidence to keep (redacted), and deletion at close. Data protection obligations still apply.
Contacts and stop rules: a named technical contact, an out-of-hours number, and the right for either party to pause testing. Critical findings, such as cross-tenant data access, are reported the same day rather than held for the final report.

Continuous and point-in-time API testing

A yearly test confirms the state of the API on the days tested. The NCSC describes penetration testing as assurance over your vulnerability management, not the main way vulnerabilities are found, and warns that long gaps leave room for new issues. APIs change weekly, so most programmes combine several layers.

Approach	Strengths	Limits	Best fit
Point-in-time manual test	Finds logic and authorisation flaws; human judgement on impact	Snapshot; cost limits frequency	Before major releases, new APIs, annual assurance
Continuous API testing (automated, in pipeline or scheduled)	Catches regressions, new endpoints and misconfiguration quickly	Weak on business logic unless authorisation tests are written for it	High change APIs with mature CI/CD
Penetration testing as a service	Testers retest on demand; findings tracked in a portal	Depth depends on hours bought per period	Organisations with many APIs and frequent releases
Bug bounty or vulnerability disclosure	Breadth of researchers; ongoing	Uneven coverage; needs triage capacity	Mature programmes after a baseline test

Decision guidance: a small organisation with one or two APIs gets most value from a grey-box manual test each major release plus ASVS authorisation tests in the pipeline. A large organisation with many teams should first fix inventory (you cannot test what you do not know exists), then risk-tier APIs: external, data-rich and multi-tenant APIs get manual testing at least annually and after significant change, while lower-tier internal APIs rely on automated testing. See the Bug Bounty and Vulnerability Disclosure Guide and the Penetration Testing Provider Buyer's Guide.

Running the engagement: a phased approach

Prepare inventory and model (weeks before): confirm API descriptions, versions and hosts; write the role and tenant matrix; name sensitive business flows.
Agree rules of engagement: scope, environments, rate ceilings, excluded operations, data handling, contacts, cloud provider rules, critical finding escalation and stop conditions, all in writing and signed.
Issue test identities: create accounts and keys per the NHI table above; seed test objects owned by each account so cross-account checks are meaningful.
Pilot day: start in pre-production or with low rates; confirm monitoring sees the traffic, nothing breaks and the tester's credentials work as intended.
Main testing: the provider covers the agreed categories and the authorisation matrix, with daily check-ins on critical issues.
Close down (rollback): revoke every test identity, remove seeded data, restore any temporarily relaxed controls (allow lists, WAF exceptions), and confirm deletion of engagement data held by the provider.
Report, fix and retest: triage findings, assign owners and dates, then retest fixes within the agreed window.

Findings, reporting and remediation

The NCSC says a report should cover the issues found, the tester's risk assessment, a resolution method for each, an opinion on the accuracy of your own vulnerability assessment and advice on improving it. For APIs, also ask for the following.

Precise location: API, version, operation and parameter, plus the role pair or tenant pair involved for authorisation findings.
Business impact: what data or action is exposed, to whom, at what scale. A BOLA on a single test record that reaches every customer record is critical; say so.
Root cause class: missing object ownership check, gateway-only authorisation, mass assignment, unlisted version. Classes matter more than single endpoints, because one missing check usually affects many operations.
Fix and verification: fix centrally (shared authorisation middleware or policy engine), add an automated test, then retest. Track the ASVS requirement each fix satisfies.
Redacted evidence: requests and responses with secrets and personal data masked.

Risk decisions stay with you. The NCSC notes that proposed fixes are not the only options: removing unneeded functionality, compensating controls and better monitoring are valid choices, and risk assessment should not be fully outsourced to testers.

Detection and measurement

Use the test to check that monitoring works as well as code. During the engagement, ask whether your API gateway and security monitoring flagged the tester's authorisation probing, enumeration of object IDs and access to unlisted versions. Afterwards, track these measures.

Inventory coverage: share of live API hosts and versions found by testers that were already in your inventory (target: all).
Authorisation coverage: share of operations with an automated BOLA and BFLA test in the pipeline.
Time to remediate: median days from report to verified fix, by severity.
Repeat finding rate: share of findings in the same class as a previous test (should fall).
Detection rate: share of tester activity classes that raised an alert.
Credential closure: test identities revoked within 24 hours of engagement end (target: 100%).

Common failure patterns

One account, one role: the tester receives a single token, so BOLA and BFLA cannot be tested properly and the report shows mostly configuration issues.
Testing the documented API only: old versions and undocumented hosts are left out. In the T-Mobile API breach, an attacker pulled data on about 37 million accounts through a single API for roughly six weeks before detection; T-Mobile has not said how the API was abused, but the case shows why API inventory and monitoring belong in scope.
Forgotten test identities: test accounts and keys outlive the engagement. In the McHire default password flaw, a test administrator account dormant since 2019 accepted a default password, and an internal API that fetched records by sequential ID did not check entitlement.
Gateway-only authorisation: the gateway checks that a token is valid but the service never checks object ownership, so every finding reappears after each release.
Secrets in reports: live keys and tokens are pasted into reports, tickets or shared drives and never rotated.
Fixing the endpoint, not the class: one operation is patched while sibling operations keep the same missing check.

Framework mapping

Framework	Reference	Relevance
NIST SP 800-53 Rev. 5	CA-8 Penetration Testing; CA-8(1) Independent Penetration Testing Agent or Team; SA-11 Developer Testing and Evaluation; RA-5 Vulnerability Monitoring and Scanning; AC-6 Least Privilege	Test requirement, independence, developer testing and test credential scoping
NIST CSF 2.0	ID.RA-01; ID.IM-02	Vulnerabilities identified and validated; improvements from security tests
OWASP ASVS 5.0	V8.2.1, V8.2.2, V8.2.3; chapter V4 API and Web Service	Verifiable authorisation requirements behind BOLA, BFLA and BOPLA
OWASP WSTG v4.2	WSTG-ATHZ-04; WSTG-APIT-01	IDOR and GraphQL test cases
CIS Controls v8.1	Control 16 Application Software Security; Control 18 Penetration Testing	Programme level testing requirements
MITRE ATT&CK	T1190 Exploit Public-Facing Application; T1528 Steal Application Access Token	Adversary behaviour the test emulates and monitoring should detect

Practitioner checklist

Maintain an API inventory with versions, hosts and owners, and give it to testers.
Write a role and tenant authorisation matrix before every API test.
Provide at least two accounts per role across at least two tenants, with seeded objects.
Issue dedicated, scoped test keys through a secrets manager and revoke them on the last day.
Agree rate ceilings, excluded operations, data handling and cloud provider rules in signed rules of engagement.
Require same-day reporting of critical findings and of any discovered live secret.
Ask for coverage against each OWASP API Security Top 10 2023 category in the report.
Fix authorisation centrally and add ASVS V8.2 tests to the pipeline before retesting.
Check whether monitoring detected the test and track repeat finding rate across tests.

API Penetration Testing Guide: Scoping, Authorisation Flaws and Reporting