API security: list every endpoint, then test each one by role, record and method
An API is every route your screens, apps and integrations call, and each route has to refuse the wrong caller on its own.
This guide maps the OWASP API Security Top 10 2023 onto one worked example: an OpenAPI endpoint register, checked against the routes your code and logs show, turned into a matrix of roles, records and HTTP methods that covers object access, writable fields, alternate methods, pagination, rate limits, error responses and undocumented endpoints.
In this guide
Endpoint register and role, record and method test matrix
An illustration, not a client. The API, at the invented host api.hire.lab.test, belongs to an invented equipment-hire business, and its operations, accounts and records were written for this page.
How to use itHide the instructions
Roles: customer users, who belong to a customer organisation and share its bookings; depot staff, who see every booking and change booking status; and administrators, who also manage customer accounts and credit limits. Test accounts: cust-a1 and cust-a2 in organisation A, cust-b1 and cust-b2 in organisation B, staff-1 and staff-2, and admin-1 and admin-2, on a staging copy with seeded test records: bookings BK-1001 (organisation A) and BK-2001 (organisation B), invoices INV-501 (A) and INV-601 (B), quote Q-310 and customer account C-77. The register, with where each line was seen: L1 GET /v2/equipment, listEquipment, marked {} in the specification so anonymous (specification, code, traffic); L2 GET /v2/bookings, listBookings, with cursor and pageSize and a documented maximum of 50 (all three); L3 POST /v2/bookings, createBooking (all three); L4 GET /v2/bookings/{bookingId}, getBooking (all three); L5 PATCH /v2/bookings/{bookingId}, updateBooking, where customers may write startDate, endDate and siteAddress and staff may also write status (all three); L6 POST /v2/bookings/{bookingId}/cancel (all three); L7 GET /v2/invoices/{invoiceId} (all three); L8 POST /v2/quotes/{quoteId}/sms, staff only, documented at 5 texts per account per hour, each sending a paid text message (all three); L9 GET /v2/admin/customers, administrators only (all three); L10 PATCH /v2/admin/customers/{customerId}, creditLimit and status, administrators only (specification and code); L11 GET /v2/bookings/{bookingId}/history (specification only); L12 POST /v2/bookings/import (code only); L13 GET /v2/internal/diagnostics (code and traffic); L14 GET /v1/bookings/{bookingId} (access log only, from an older app build, served by a v1 deployment that is still running). Rows M1 to M14 turn that register into the matrix. To use it on your own API, build your register first, keep every column, write the expected result before you send anything, and fill in the last column for each row. Run it only against an API you own, on a staging environment you control, with your own test accounts and test records, and without load: one request per check, and for a limit only enough requests to see one refusal.
14 rows
Row and what it tests
Register lines it covers
M1. The register line: one per method and path
- Register lines it covers
- Every operation found in the specification, the code or the traffic.
- Worked example on the invented API
- L4 written out: GET /v2/bookings/{bookingId}, getBooking. Seen in the specification, the code and the access log. Security: bearer token; customer (own organisation), staff and administrator. Object: bookingId in the path, a booking. Read fields: customers get dates, site address, equipment and price, and staff also get internalNotes. Write fields: none. Limit: none documented. Errors: 401 and 404 in the documented error schema. Host and version: api.hire.lab.test, v2.
- Expected result, written before sending
- Every line names where it was seen and the roles allowed, and has an entry for objects, fields, limits and errors, even when the entry is none.
- Blank form: what to record for your own API
- Method; path; operationId; seen in (specification, code, traffic); effective security requirement and roles allowed; where the object identifier sits and what record it names; fields each role may read and write; page size maximum; documented limit and what it counts against; whether each call costs money; documented errors; host; version; deprecated flag.
M2. Specification, code and traffic compared (API9:2023)
- Register lines it covers
- The whole register.
- Worked example on the invented API
- L10 appears in the specification and the code but not the traffic, L11 only in the specification, L12 only in the code, L13 in the code and traffic but not the specification, and L14 only in the access log.
- Expected result, written before sending
- Each line seen in fewer than three places gets a decision before testing: document it and add it to the matrix, put it behind the same checks, or remove it. L14 goes through rows M3 to M13, as row M14 describes.
- Blank form: what to record for your own API
- For each line seen in fewer than three places: where it was seen, who owns it, the decision, and the date the decision was confirmed on the running API.
M3. Operations open without a session
- Register lines it covers
- Lines whose effective security requirement is empty or {}, then every line.
- Worked example on the invented API
- Only L1 is marked {} in the specification. With no session, send one request to each of L1 to L14, using test records for anything that writes.
- Expected result, written before sending
- L1 answers 200. Every other line answers 401, except L11, which answers 404 because its route was removed, and L13, which answers 401 or cannot be reached from outside.
- Blank form: what to record for your own API
- Limits: your own API, a staging environment you control, your own test records only, no load. Each operation the specification marks anonymous and whether that is intended, then the no-session status for every line.
M4. Object authorisation on reads (API1:2023)
- Register lines it covers
- L4, L7, L14 and every read that names a record.
- Worked example on the invented API
- BK-1001 requested by cust-a1, cust-a2, cust-b1 and staff-1. INV-601 requested by cust-a1. The same requests repeated on L14.
- Expected result, written before sending
- cust-a1, cust-a2 and staff-1 get 200 for BK-1001. cust-b1 gets the same 404, with the same body, as for a booking that does not exist, and so does cust-a1 for INV-601.
- Blank form: what to record for your own API
- For each operation: the record and its owner, each account tried, the expected and actual status, and whether the refusal matched the not-found response.
M5. Object authorisation on writes (API1:2023)
- Register lines it covers
- L5, L6 and every write that names a record.
- Worked example on the invented API
- cust-b1 sends PATCH /v2/bookings/BK-1001 with a new endDate, then POST /v2/bookings/BK-1001/cancel. BK-1001 is a test booking.
- Expected result, written before sending
- Both get the not-found response, and BK-1001 reads back unchanged as cust-a1.
- Blank form: what to record for your own API
- Limits: your own API, a staging environment you control, your own test accounts and test records only, no load. The write tried, the account, the status, and the record as its owner reads it back afterwards.
M6. Function-level authorisation (API5:2023)
- Register lines it covers
- L8, L9, L10, L12 and L13, and any line one role should not call.
- Worked example on the invented API
- cust-a1 and staff-1 call GET /v2/admin/customers and send PATCH /v2/admin/customers/C-77 with a new creditLimit. cust-a1 calls POST /v2/quotes/Q-310/sms and POST /v2/bookings/import with one test booking. Test quote Q-310 holds a phone number you control.
- Expected result, written before sending
- 403 for each, C-77 unchanged, no text message sent and no booking imported. admin-1 gets 200 on L9 and L10.
- Blank form: what to record for your own API
- Limits: your own API, a staging environment you control, your own test accounts and test records only, no load. For each function: the roles allowed, each role tried, the status, and the side effect checked afterwards, such as the record read back or the message log.
M7. Properties returned (API3:2023)
- Register lines it covers
- L2, L4, L7, L9 and every response that returns a record.
- Worked example on the invented API
- The response to GET /v2/bookings/BK-1001 for cust-a1 and for staff-1, compared field by field with the schema in the specification and with what each screen shows.
- Expected result, written before sending
- cust-a1 receives no internalNotes, costPrice or staff contact fields. staff-1 receives internalNotes.
- Blank form: what to record for your own API
- Each field in the response for each role, marked documented, shown on screen, or neither.
M8. Properties accepted, or mass assignment (API3:2023)
- Register lines it covers
- L3, L5, L10 and every write that takes a body.
- Worked example on the invented API
- cust-a1 sends PATCH /v2/bookings/BK-1001 with a new endDate, plus status set to returned, depositWaived set to true and organisationId set to organisation B.
- Expected result, written before sending
- endDate changes. status, depositWaived and organisationId are refused or ignored, and BK-1001 reads back with them unchanged.
- Blank form: what to record for your own API
- Limits: your own API, a staging environment you control, your own test accounts and test records only, no load. The fields each role may write, from the register; each extra field tried; the status; and each value as read back afterwards.
M9. Alternate HTTP methods (API5:2023, API8:2023)
- Register lines it covers
- Every path in the register.
- Worked example on the invented API
- On /v2/bookings/{bookingId} with test booking BK-1001: DELETE, PUT and POST as cust-a1, HEAD as cust-b1, OPTIONS with no session, and a method name the server should not know.
- Expected result, written before sending
- DELETE, PUT and POST get 405 with an Allow header listing only the methods in the register: GET and PATCH, plus HEAD or OPTIONS if you decided to answer them. HEAD as cust-b1 gets the same status as GET. The unknown name gets 405 or 501. BK-1001 still exists.
- Blank form: what to record for your own API
- Limits: your own API, a staging environment you control, your own test accounts and test records only, no load. For each path: the methods in the register, the methods the server answers, the Allow header returned, and the status for each method and role.
M10. Method override headers (WSTG-CONF-06)
- Register lines it covers
- Every path where a method was refused with 405 in M9.
- Worked example on the invented API
- The refused DELETE on BK-1001 replayed with X-HTTP-Method: DELETE added, then with X-HTTP-Method-Override and X-Method-Override in turn, and the same three headers on a POST to the same path.
- Expected result, written before sending
- Each one still refused, and BK-1001 still exists.
- Blank form: what to record for your own API
- Limits: your own API, a staging environment you control, your own test accounts and test records only, no load. For each path: each override header tried, the status, and whether the record changed.
M11. Lists and pagination (API4:2023)
- Register lines it covers
- L2, L9, and any search or export.
- Worked example on the invented API
- As cust-a1: GET /v2/bookings with pageSize 500, 0, -1 and abc. The cursor from cust-b1's second page replayed as cust-a1. An organisationId query parameter naming organisation B.
- Expected result, written before sending
- pageSize capped at 50 or refused with the documented 400 error. The replayed cursor returns only organisation A bookings, or an error. The organisationId parameter is ignored or refused.
- Blank form: what to record for your own API
- The documented maximum, each value tried, the number of records returned, and any record from another organisation.
M12. Rate limits and paid operations (API4:2023)
- Register lines it covers
- L8 and every line with a documented limit, on a staging copy of each host in the register.
- Worked example on the invented API
- L8 is documented at 5 texts per account per hour, and each call sends a paid text message. On staging, as staff-1, send texts for test quote Q-310 to a phone number you control, or with the text provider in test mode, until one is refused.
- Expected result, written before sending
- Texts 1 to 5 are sent and the sixth gets 429 with a Retry-After header. The provider's log shows five messages, and the provider account has a spending limit or billing alert.
- Blank form: what to record for your own API
- Limits: your own API, a staging environment you control, your own test accounts and test records only, and no load: lower a high limit on staging first, as the rate limits section describes, then stop at the first refusal. The documented limit and what it counts against, the number of the request that was refused, the status and Retry-After value, the host, and the provider's spending limit or billing alert.
M13. Error responses (API8:2023)
- Register lines it covers
- Every line, starting with those that take a body.
- Worked example on the invented API
- To L3: a malformed JSON body, startDate set to "next week", the body sent as text/xml, and a body larger than the documented limit. To L4: bookingId set to abc.
- Expected result, written before sending
- Each answer is a 4xx status in the documented error schema (400, 400, 415 and 413 for L3; 400 or 404 for L4), with no stack trace, file path, SQL, library version or internal host name.
- Blank form: what to record for your own API
- Limits: your own API, a staging environment you control, your own test accounts and test records only, no load. Each request that produces an error, the status, whether the body matched the documented error schema, and anything internal it revealed.
M14. Old versions and other hosts (API9:2023)
- Register lines it covers
- L14, and every host or version in the register other than the current one.
- Worked example on the invented API
- Rows M3 to M13 run against a staging copy of the v1 deployment that serves L14.
- Expected result, written before sending
- The same results as on v2, or the v1 deployment is retired and its host stops answering.
- Blank form: what to record for your own API
- Limits: your own API, a staging copy you control, your own test accounts and test records only, no load. For each host and version: its environment, who should be able to reach it, the API version, and the result of each row run against its staging copy.
What API security covers, and where the API sits
An API is the set of HTTP routes that software calls to read and change your data.
In a web application with a separate front end, the screens a customer sees are one client of that API. A mobile app, a partner integration, an automation tool and anyone holding a copy of a request are others, and none of them has to go through your screens.
API security is the work of making each route enforce the rules itself: who may call it, which records and fields they may touch, which methods it answers, how often, and what it says when something goes wrong.
Two standards frame the work, and neither enforces anything on your server. RFC 9110, the HTTP semantics standard, says that once defined, a standardised method ought to have the same semantics when applied to any resource, though each resource determines for itself whether those semantics are implemented or allowed.
The OpenAPI Specification defines a standard, language-agnostic description of an HTTP API, which lets people and tools discover and understand what a service can do without its source code.
Whether an operation checks the caller, the record, the field and the method is decided in your code, and that is what this page tests.
ASVS 5.0, OWASP's verification standard, has a chapter for APIs and web services. It notes that authentication, session management and input validation concerns from its other chapters also apply to APIs, so the chapter cannot be taken out of context or tested in isolation.
That is why this page is a map rather than a deep dive. The entries below point to the guides in this library that cover each mistake in depth, and this page shows how to find every operation where one could occur.
The OWASP API Security Top 10 2023, and where each entry is tested
OWASP keeps a separate top ten for APIs.
Its release notes say the 2023 edition is the second, released four years after the first, and that it combined Excessive Data Exposure and Mass Assignment, focusing on their common root cause: authorisation validation failures at the level of an object's properties. The same notes call the list a forward-looking awareness document that does not replace OWASP's other top ten lists.
Below are the ten entries with OWASP's ids, what OWASP's list says about each, and where the matrix on this page or another guide takes it up.
- API1:2023 Broken Object Level Authorization. OWASP says APIs tend to expose endpoints that handle object identifiers, and that object level authorisation checks should be considered in every function that accesses a data source using an ID from the user. Matrix lines M4 and M5 test it, and the broken access control guide explains the check in depth.
- API2:2023 Broken Authentication. OWASP says authentication mechanisms are often implemented incorrectly, letting attackers compromise tokens or assume other users' identities. The register records the scheme each operation expects, and the authentication failures, JWT security and OAuth and OpenID Connect guides cover the flows and tokens themselves.
- API3:2023 Broken Object Property Level Authorization. OWASP's list says this entry combines API3:2019 Excessive Data Exposure and API6:2019 Mass Assignment. In plain terms, it covers properties a caller should not read and properties a caller should not change. Lines M7 and M8 test both sides, and the sensitive data exposure and mass assignment guides cover each one.
- API4:2023 Unrestricted Resource Consumption. OWASP notes that satisfying requests takes resources such as network bandwidth, CPU, memory and storage, that some resources, such as email, SMS and phone calls, are made available by service providers and paid for per request, and that successful attacks can lead to denial of service or higher operating costs. Lines M11 and M12 check page sizes and documented limits, and the rate limiting guide covers how to design a limit.
- API5:2023 Broken Function Level Authorization. OWASP says complex access control policies with different hierarchies, groups and roles, and an unclear separation between administrative and regular functions, tend to lead to authorisation flaws. Lines M6 and M9 test functions by role and by method, and the broken access control guide covers vertical access in depth.
- API6:2023 Unrestricted Access to Sensitive Business Flows. A flow such as buying a ticket or posting a comment, exposed without allowing for the harm of excessive automated use, which OWASP notes does not necessarily come from implementation bugs. The register can flag these flows, but the rules for them come from your business, and the business logic guide covers them.
- API7:2023 Server Side Request Forgery. OWASP says these flaws can occur when an API fetches a remote resource without validating the URI a user supplied. The SSRF guide covers it. In the register, mark every operation that accepts a URL.
- API8:2023 Security Misconfiguration. OWASP's list says APIs and the systems supporting them typically contain complex configurations that engineers can miss. Two of the conditions on its entry page are in the matrix: unnecessary features enabled, with HTTP verbs among its examples (M9), and error messages that include stack traces or expose other sensitive information (M13). Its CORS condition belongs to the CORS misconfiguration guide, and the security misconfiguration guide covers settings across the wider stack.
- API9:2023 Improper Inventory Management. OWASP says APIs tend to expose more endpoints than traditional web applications, which makes proper, updated documentation and an inventory of hosts and deployed API versions important. That is the register itself, with lines M2 and M14.
- API10:2023 Unsafe Consumption of APIs. According to OWASP, developers tend to trust data from third-party APIs more than user input, and attackers go after those integrated services instead of the target API. Your own matrix does not reach this one, and the section on what the matrix cannot show explains why.
Building the endpoint register from three sources
The register has one line per method and path.
Start it from your OpenAPI document if you have one, because the specification already holds many of the fields a line needs. Its Paths Object holds the relative paths to the individual endpoints and their operations. Each Path Item Object can define an operation for GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH, TRACE and QUERY, plus an additionalOperations map for any other method.
Each Operation Object can carry an operationId, its parameters, its request body, its possible responses, a deprecated flag and a security requirement of its own.
Read the security fields closely. A Security Requirement Object lists the schemes required to run an operation, and for schemes other than OAuth 2.0 and OpenID Connect, its array may list role names that are required but are not otherwise defined or exchanged in-band.
An empty requirement, written {}, indicates that anonymous access is supported. A security list on an operation overrides the one declared for the whole API, and an empty array there removes the top-level declaration.
A few lines in one file can therefore mark an operation as needing no credentials while every other operation asks for a token. Record the effective requirement of each operation, not the default at the top of the file.
Then check the document against what is running, because a specification describes the API someone meant to build. OWASP's API reconnaissance test, WSTG-APIT-01, appears in the edition of its testing guide that the site labels Latest, which it says may frequently change, and this page uses it as it read on 14 November 2026.
The test warns that a public API's Swagger or OpenAPI document, however well intentioned, may not be accurate and may not disclose the complete API, and that documentation can be outdated, inaccurate or incomplete. Its first objective is to find all API endpoints the backend supports, documented or undocumented.
The OpenAPI Specification itself allows a Paths Object to be present but empty, and a Path Item to be empty, as an additional layer of access control over the documentation. A published document can therefore show less than the API serves, on purpose.
- The specification: every path and operation in the OpenAPI document, with its effective security requirement, its parameters and its deprecated flag.
- The code: every route your framework, router or API gateway registers. WSTG-APIT-01 says that if you have the server-side source code, you should extract the endpoints from it. If your framework can print its own route table, that is the list.
- The traffic: every method and path in your access logs and gateway logs, and in your browser's network panel while you use the application as each role. WSTG-APIT-01 makes the same point about accounts: sample accounts at different privilege levels let browsing reach as much functionality as possible.
Comparing the three lists
Lay the three lists side by side and give each line a column saying where it was seen. A route in the code and the logs but not the specification is undocumented. A route in the specification but not the code is stale documentation, or is served by something else.
A route found only in the logs is the one to chase first, because it may be an old version, another host or a service nobody listed.
OWASP's API9:2023 names old API versions, and endpoints left running unpatched with weaker security requirements, as the way threat agents usually get unauthorised access. Its first example scenario is a rate limit enforced in a separate component in front of the main API host, missing on a beta host that ran the same API.
The entry also recommends documenting all aspects of an API, such as authentication, errors, redirects, rate limiting, cross-origin resource sharing policy, and endpoints with their parameters, requests and responses. A register line is that documentation, kept per operation.
What each register line records
Each line feeds the matrix, so it records the facts the tests need rather than a description of the endpoint. The first row of the matrix on this page shows one line written out for the invented API, and its last column is the blank form for yours.
- Method and path, as the server matches them, with the operationId if the specification has one.
- Where the line was seen: specification, code, traffic, or a combination.
- The effective security requirement and the roles allowed to call the operation, listed by name.
- Where an object identifier sits (path, query, body or header) and which kind of record it names.
- The fields each role may read in the response and may write in the request.
- For list operations, the page size parameter and its documented maximum.
- The documented rate limit, what it counts against, and whether each call costs money, such as sending an email or a text message.
- The documented error responses, and the host and version the line belongs to.
From register to matrix: callers, records and fields
The matrix is the register multiplied out.
Each line becomes a row, and the columns are the callers: no session, each role, a second account in the same role that does not own the record, and an account in a second customer organisation if your API serves more than one.
Before sending anything, write the expected result in every cell from your own rules. A cell where you cannot say what should happen is a gap in the rules, and it is better found on paper than in a response.
Three kinds of authorisation sit behind rows M4 to M9, and OWASP files each under its own entry. Object-level checks ask whether this caller may act on this record (API1:2023). Function-level checks ask whether this caller may run this operation at all (API5:2023). Property-level checks ask which fields of the record this caller may read and write (API3:2023).
ASVS 5.0 states the same three as requirements 8.2.1 and 8.2.2, both at Level 1, and 8.2.3, at Level 2: function-level access, data-specific access and field-level access, each restricted to consumers with explicit permissions.
Two warnings from OWASP shape the rows. API5:2023 says not to assume an endpoint is regular or administrative only from its URL path, because administrative endpoints can sit under other paths beside regular ones. Every row therefore gets every role, not only the rows under /admin.
API1:2023 says that comparing the user ID in the session, such as one extracted from a JWT, with the ID parameter is not a sufficient solution and could address only a small subset of cases.
The object rows therefore use records owned by another account in the same role and in another organisation, not just a different number in the path.
The broken access control guide goes deep on object checks and on whether a refusal should be 404 or 403, the mass assignment guide on writable fields, and the sensitive data exposure guide on fields returned. What the matrix adds across an API is coverage: every operation, every caller and every method, so no route is checked only because someone remembered it.
Alternate HTTP methods and method override headers
A register line names one method, but the server decides which methods a path answers.
RFC 9110 says all general-purpose servers must support GET and HEAD, and that all other methods are optional. An origin server that receives a method it recognises and implements, but which the target resource does not allow, should respond 405 Method Not Allowed, and one that receives a method it does not recognise or implement should respond 501 Not Implemented. A 405 response must carry an Allow header listing the target resource's supported methods.
That Allow header gives you a comparison with the register for one request. If a path the register lists as GET and PATCH answers a DELETE with anything but a refusal, or names DELETE in its Allow header, the code has an operation the specification does not describe.
OWASP's API5:2023 asks whether a user can perform sensitive actions they should not have access to by changing the HTTP method, for example from GET to DELETE.
The REST Security Cheat Sheet says to apply an allowlist of permitted methods, reject everything else with 405, and make sure the caller is authorised to use the incoming method on the resource collection, action and record.
HEAD and OPTIONS need their own cells. RFC 9110 defines HEAD as identical to GET except that the server must not send content, and says the server should send the same header fields it would have sent for GET, though it may leave out header fields whose value is determined only while generating the content.
WSTG-CONF-06, the HTTP methods test in WSTG v4.2, sends methods such as HEAD, POST and PUT, and invented method names, to a page that should force a login, and treats a 200 OK that is not the login page as a possible bypass of authentication or authorisation.
If a protected GET refuses a lower role but HEAD answers 200, the check is tied to the method rather than to the operation.
RFC 9110 also covers actions chosen by a parameter. Where parameters in the target URI select an action, and the action is unsafe, the resource owner must disable or disallow it when the resource is accessed with a safe method such as GET. A register line like GET /items?action=delete is worth its own row.
Method override headers
Some frameworks let a request name a different method in a header. WSTG-CONF-06 lists X-HTTP-Method, X-HTTP-Method-Override and X-Method-Override, and its test replays a PUT or DELETE that returned 405 with one of those headers added, watching for a different status such as 200. Add one override row for each path where M9 produced a 405.
How many methods to answer
The standards draw this line in different places. RFC 9110 requires general-purpose servers to support GET and HEAD. OWASP's API8:2023 advises being specific about which HTTP verbs each API can be accessed by and disabling the rest, with HEAD as its example. ASVS 5.0 requirement 4.1.4, at Level 3, asks that only methods the application or its API explicitly supports, including OPTIONS during preflight requests, can be used, and that unused methods are blocked.
Whichever line you choose, write it in the register, and give every method a path does answer the same authorisation as the operation it stands for.
Lists, search and pagination
List operations hand back many records in one response, which makes them an easy place to take too much.
OWASP's API4:2023 includes the number of records per page returned in a single request and response among the limits that make an API vulnerable when they are missing or set inappropriately, for example too low or too high. It recommends server-side validation of the query string and request body parameter that controls how many records come back, and a defined maximum size for all incoming parameters and payloads, such as string lengths and the number of elements in arrays.
Give each list operation in the register its documented maximum page size, then add these rows to the matrix:
- A page size above the documented maximum, zero, a negative number and a value that is not a number. The server should cap or refuse each one, and the register says which.
- A cursor or page token taken from one account's listing and replayed by an account in another organisation. The second account should get only its own records, or an error.
- Filter and sort parameters that name another organisation, owner or status the role cannot see, including parameters the documentation does not mention.
- Search and export operations, which are lists under another name. Each one gets the same rows.
Which records a list returns
Whether a list returns records the caller may not see is an object-level question, and the broken access control guide covers lists, search and filters in that light. The rows here add the size and cursor checks that belong to the API as a whole.
Rate limits: the documented number and one refusal
API4:2023 recommends rate limiting, which it describes as a limit on how often a client can interact with the API within a defined timeframe.
It wants that limit fine tuned to what the business needs, with stricter policies on the endpoints that might require them. It also points to resources paid for per request, such as email, SMS and phone calls, and recommends spending limits for all service providers and API integrations, with billing alerts where a spending limit is not possible.
The matrix checks that each documented limit exists and answers correctly. It does not measure how much traffic the API can take. For each line with a limit, record the number the documentation gives and the key it counts against, such as the account, the API key or the address.
Then, on staging, with the limit lowered where it is high so that a handful of requests reach it, send requests until one is refused, and keep that refused response.
RFC 6585 defines 429 Too Many Requests for a user who has sent too many requests in a given amount of time, and says the response may include a Retry-After header saying how long to wait.
Run the row on a staging copy of every host and version in the register, because the OWASP API9:2023 example above is a limit that existed on one host and not on another serving the same API. The rate limiting guide covers how to choose keys and windows, and what a useful refusal says.
Measuring how much traffic the API can take, including denial-of-service testing, belongs to a load-testing specialist and needs your host's written approval.
Error responses: what a failure tells the caller
An error is a response like any other, and callers read it.
OWASP's API8:2023 counts error messages that include stack traces, or expose other sensitive information, among the conditions that can make an API vulnerable, and recommends, where applicable, defining and enforcing all API response payload schemas, including error responses, to keep exception traces and other valuable information from being sent back to attackers.
The REST Security Cheat Sheet says to respond with generic error messages and not to pass technical details such as call stacks to the client. ASVS 5.0 requirement 16.5.1 (Level 2) wants the consumer to get a generic message whenever an unexpected or security-sensitive error occurs, so that no sensitive internal system data, such as stack traces, queries, secret keys and tokens, is exposed.
Your OpenAPI document can already say what an error looks like, because each operation can list the possible responses it returns. The matrix rows send the inputs that produce errors and compare each answer with the documented error shape:
- A malformed JSON body, a field of the wrong type, a missing required field and an identifier in the wrong format.
- A request body with a content type the operation does not accept. The REST Security Cheat Sheet says to reject unsupported media types with 415 Unsupported Media Type.
- A body larger than the documented limit, which the same cheat sheet says to reject with status 413.
- A method the path does not allow, which should produce the 405 and Allow header described above.
- A record that does not exist and a record the caller may not see. The broken access control guide explains why those two answers should match.
Reading each error body
Read each body for stack traces, file paths, SQL fragments, framework or library versions and internal host names, and keep the response. MITRE catalogues the weakness as CWE-209, Generation of Error Message Containing Sensitive Information: the product generates an error message that includes sensitive information about its environment, users or associated data. Error messages elsewhere in the application are the subject of the sensitive data exposure guide.
API security testing on your own API
Run the matrix only against an API you own, on a staging environment you control, with test accounts you created for each role.
Testing an API that belongs to someone else is not what this page describes. Read your hosting provider's terms before you start; this page makes no statement about what any host allows. Use two test accounts per role, so access can be tried in both directions between people in the same role, and accounts in two customer organisations if your API serves more than one.
- Build the register from the specification, the code and the traffic, and decide what to do with every line seen in only one place before testing starts.
- Before the first request, fill in the expected result of every cell from your own access rules.
- Use staging with seeded test records, and run anything that writes or deletes only against records created for the test. Keep a list of what you created so it can be removed.
- Change one thing per request: the session, the record, the field or the method. Keep the request and response for every cell, passes included, with tokens and personal details redacted.
- For limits, send only enough requests to see one refusal.
- Run the matrix again when the register changes: a new operation, a new role, a new version or a new host.
Keeping the matrix as a regression test
OWASP's API1:2023 recommends writing tests to evaluate the authorisation mechanism and not deploying changes that make those tests fail. The matrix is a ready list of those tests. Turn each passing row into an automated check that runs before release, so a later change that drops a check fails the build instead of reaching customers.
An API security checklist drawn from the standards
These are API security best practices, each credited to the source that recommends it.
The matrix tests some of them; the others are review questions it does not test. Use them as a review list for each new operation before it is released.
- Inventory every API host with its environment, who should have network access and its API version, as API9:2023 recommends, and make documentation available only to those authorised to use the API.
- Keep production data off non-production deployments. API9:2023 says that where this cannot be avoided, those endpoints should get the same security treatment as production.
- Put an authorisation check in every function that uses input from the client to reach a database record (API1:2023), and deny all access by default, with explicit grants to specific roles for every function (API5:2023).
- Allow changes only to the properties the client should update, and keep returned data to the minimum the endpoint needs (API3:2023).
- Be specific about which HTTP methods each API can be accessed by and disable the rest (API8:2023), and reject requests outside an allowlist of permitted methods with 405 (REST Security Cheat Sheet).
- Validate the parameter that controls how many records come back, and set maximum sizes for parameters and payloads (API4:2023).
- Tune rate limits to business needs, with stricter policies for endpoints that require them, and configure spending limits for every service provider, or billing alerts where a spending limit cannot be set (API4:2023).
- Where applicable, define and enforce the response schema of every operation, errors included (API8:2023), and return a generic message when an unexpected or security-sensitive error occurs (ASVS 5.0 requirement 16.5.1).
- Keep passwords, tokens and API keys out of URLs, where web server logs can capture them, and do not rely on API keys alone for sensitive, critical or high-value resources (REST Security Cheat Sheet).
- Validate data received from third-party APIs before using it, use TLS for every integration, and keep an allowlist of places an integration may redirect you to rather than following its redirects blindly (API10:2023).
What your own matrix cannot show
A matrix is only as complete as its register.
A route that appears in none of the three sources, a host nobody recorded, or a parameter the code reads but no client sends will not have a row. OWASP's reconnaissance test also looks in places a register built from your own files can miss, such as older versions of the documentation and the HTML and JavaScript sent to clients.
Some entries sit outside what your own requests can observe. Among other conditions, API10:2023 says an API might be vulnerable if it does not properly validate data gathered from other APIs, blindly follows redirections, or does not implement timeouts for its interactions with third-party services. Those are decisions in your code and configuration, and a request matrix sees only their result.
The outbound fetches behind server-side request forgery are similar, and the SSRF guide covers them. Business flows that cause harm only in bulk (API6:2023) need your rules written down before any test can judge them.
Two kinds of API have guides of their own. For time-boxed engagements, OWASP's reconnaissance test advises asking early for machine-readable API artefacts, and for non-REST APIs in scope, such as GraphQL, for schemas, or exported schemas when introspection is disabled. The GraphQL guide in this library covers schema and resolver testing.
A webhook endpoint that receives payment events is called by the payment provider rather than by your users, and the Stripe webhook security guide covers its signature and replay checks.
Finally, the matrix tests behaviour you can observe on the build you ran it against. It does not show that the same mistake is absent on paths you did not test, and a clean run is a result for the rows you ran and nothing wider.
Where a Clever Ops test takes over
In a Clever Ops web application and API penetration test, the API in scope is the one your own application calls, and it is tested as part of the application.
Each of its routes is called directly as well as through the screens, and that includes routes no screen uses. Old API versions that still respond go into the report, and join the test after you confirm them in writing. When partners or a mobile app call the API with keys or tokens of their own, that access is scoped as a separate surface, and an API with little or no web front end is tested with the API as the main target. The mobile app itself and on-device testing are not part of the service.
Each role in scope needs two test accounts, and an application that serves more than one customer organisation needs accounts in two of them. The preferred environment is a staging copy that matches production. Where the scope includes it, read-only access to named parts of the code, such as the permission checks, is used to confirm how a control is enforced.
Destructive actions are off by default for real people's accounts and records that existed before the test, and reset, lockout and deletion checks run only on test accounts and test records where the rules of engagement allow them. Routes that cost money each time they run are checked for a missing limit with a handful of requests, which is not load testing.
We refer load and denial-of-service testing to a load-testing specialist, which needs your host's written approval, and internal networks, servers and staff devices to a network specialist.
The report records the scope as tested, including the route list and the roles and accounts used, findings with redacted evidence and a fix, and negative results for the routes and accounts tried, so the matrix you keep and the report can be read side by side.
The report is evidence that a customer, an auditor or someone else uses to make a decision, and it does not certify the application. Because Clever Ops is not CREST accredited, work for a tender or contract that requires a CREST-accredited provider is referred to one that is.
On an application that Clever Ops built or hosts, the work is a security review rather than an independent test, and the report names both the builder and the host.
Frequently asked questions
It is OWASP's list of the ten most critical API security risks. The 2023 edition is the second, released four years after the first, and runs from API1:2023 Broken Object Level Authorization to API10:2023 Unsafe Consumption of APIs. It merged the 2019 entries Excessive Data Exposure and Mass Assignment into API3:2023 Broken Object Property Level Authorization, and added Unsafe Consumption of APIs because attackers had started looking for a target's integrated services to compromise instead.
It is the place to start, not the whole list. OWASP's API reconnaissance test warns that a public API's Swagger or OpenAPI document may not be accurate and may not disclose the complete API, and the OpenAPI Specification allows the Paths Object and individual Path Items to be left empty as a layer of access control over the documentation. Compare the document with the routes your code registers and the routes in your logs, and give every line from all three a row in the matrix.
RFC 9110 says an origin server should respond 405 Method Not Allowed when it recognises and implements the method but the target resource does not allow it, and that a 405 response must include an Allow header listing the target resource's supported methods. A method the server does not recognise or implement should get 501 Not Implemented. OWASP's REST Security Cheat Sheet recommends an allowlist of methods with 405 for everything outside it.
Because a check written for one method may not run for another. RFC 9110 defines HEAD as GET without the response content and requires general-purpose servers to support both, and WSTG-CONF-06 sends HEAD and other methods to protected pages, treating a 200 that is not the login page as a possible bypass. Record in the register which methods each path answers, and give each one the same authorisation as the operation it stands for.
Not in this matrix, and not in a Clever Ops test. OWASP's API4:2023 says an API is vulnerable if at least one of a list of limits is missing or set inappropriately, and that list includes records per page and third-party spending limits. Whether a limit exists can be shown with a handful of requests on staging. For volume and denial-of-service testing, talk to a load-testing specialist, and get your host's written approval first.
Yes, within a web application and API penetration test. Partner or mobile access with its own keys or tokens is scoped as a separate surface, covering each endpoint and each key, token or account type that can call it, and where there is little or no web front end, the API is the main target. Testing happens on a staging API holding seeded data, which leaves real records untouched. The mobile app itself and on-device testing are not part of the service.
Scope the right test for your application
Tell us what you have built, who uses it and when it needs to launch. You will get a plain-English recommendation: a website audit, a web application test or a referral to a specialist.