API security testing before an agency endpoint goes public

Reference article · 5 min read

Agencies are publishing more machine interfaces than they used to. A permit system lets a contractor check application status from a phone. A billing platform returns payment history to a customer app. A case system feeds a partner jurisdiction. Each of these takes data that used to sit behind a staff login and exposes it to automated requests at machine speed.

The problems that surface in these interfaces are usually not the ones a vulnerability scanner reports. Scanners look for unpatched components, weak transport settings, and known product defects. The failures that actually expose resident records in an API are logic failures: the endpoint confirms you are signed in, but never confirms the record you asked for belongs to you. A scan can come back clean on an endpoint that hands any case file to anyone who changes a number in the request.

Authentication is not authorization

Most pre-launch reviews verify that the API requires a token or key. That is authentication, which answers who is calling. Authorization is the separate question of whether that caller may see or change that specific record, and it must be enforced on the server for every request, not in the app or web front end that normally makes the call.

That distinction drives the test plan. Testing authorization requires at least two working accounts at different privilege levels and knowledge of which records each one legitimately owns. A plan without that setup cannot find the most common class of API defect.

What to test before the endpoint is public

Object-level authorization. Sign in as resident A, capture a request for A's record, then swap in an identifier belonging to resident B. The response should be a denial, not B's data. Repeat for every endpoint that takes an identifier, including read, update, and delete.
Function-level authorization. Call an administrative or staff-only endpoint with an ordinary user's credentials. Approval, status change, refund, and bulk export functions deserve particular attention.
Excessive data in responses. Compare the raw JSON to what the user interface displays. Responses often carry dates of birth, partial identifiers, internal case notes, or staff comments that the screen never renders but any caller can read.
Mass assignment. Submit fields the client should not control, such as status, role, fee waived, or account owner, and confirm the server ignores them.
Rate limits and enumeration. Predictable identifiers plus no throttling let an entire dataset be pulled quietly. Test how many requests the endpoint accepts and what happens at the ceiling.
Forgotten versions and non-production hosts. Old versions left running rarely receive the fixes applied to the current one, and staging environments loaded with copied production data are a recurring source of exposure. Inventory every hostname and path that answers, not only the one in the documentation.
Error handling. Confirm failures return a generic message, not stack traces, query fragments, or internal hostnames.

Testing when the API is vendor-hosted

When the interface runs in a vendor's cloud, the agency usually cannot test it unannounced. Settle the arrangement before the contract is signed, not in the week before launch. Three options are common and they are not equivalent: the vendor tests and shares a report, an independent third party tests under the vendor's authorization, or a tester the agency retains works against a dedicated environment under a written rules-of-engagement document naming scope, window, accounts, and contacts. The last gives the agency the most confidence and needs the most lead time. A vendor SOC 2 report or a cloud authorization such as FedRAMP or a state equivalent says something useful about organizational controls, but none of them shows that this endpoint enforces authorization correctly.

What to require in the contract

A named testing right. The agency or its designee may test the interface at defined intervals and before major releases, with a stated notice period.
Test accounts and environment. Multiple accounts at different roles, with seeded data, at no added cost.
Remediation timelines by severity. Tie go-live and acceptance to the closure of high and critical findings, and require retesting after fixes.
Scope that includes the API itself. Many security clauses describe the hosted application generically. Say that machine interfaces, all supported versions, and non-production environments holding agency data are in scope.
Disclosure obligations. Require prompt notice of incidents affecting the interface and disclosure of known unresolved findings before acceptance.
Data minimization in responses. State that responses return only the fields the agency has approved for the use case.

Requirements for security assessment, access control, and breach notification vary by state, data type, and funding source. Confirm which ones apply with your counsel and privacy officer before finalizing terms.

Evidence to accept before go-live

Ask for a report naming the endpoints tested, the accounts and roles used, the testing dates, and the findings with severity and status. A report that is only tooling output, or that describes the web application without mentioning the interface, has not answered the question. Ask directly whether authorization was tested across multiple accounts, because that is the test most often skipped.

Keep one artifact internally: a signed statement from the technical owner that every endpoint in the published inventory was tested and that no other endpoint serving agency data is reachable from the internet. Public references give the work a shared vocabulary, including the OWASP API Security Top 10 for failure categories and NIST guidance on security testing for process. Name them in the statement of work so both sides describe the same activity.

HQT is a technology and software company that works with state and local government agencies on software development, integration, and cybersecurity, including API security review.

Frequently asked questions

Is a vulnerability scan enough to security test an API before launch?

No. Automated scanners are good at finding unpatched components, weak transport settings, and known product defects, and they should still be run. They generally cannot tell whether an endpoint correctly restricts one resident's records from another, because that requires understanding which data each account is entitled to see. Authorization testing has to be done with real accounts at different privilege levels.

Who should test an API that a vendor hosts in their own cloud?

The agency usually cannot test a vendor-hosted system without permission, so the arrangement should be settled in the contract rather than at launch. Common options are vendor testing with a shared report, an independent third party engaged under the vendor's authorization, or an agency-retained tester working in a dedicated environment under written rules of engagement. The last option gives the agency the most independent assurance and takes the most lead time to set up.

Does a vendor's SOC 2 report or FedRAMP authorization prove the API is secure?

Those documents describe organizational and platform controls, and they are useful background, but they do not demonstrate that a specific endpoint enforces record-level authorization. A cloud authorization covers the hosting environment and control processes, not the business logic of one interface. Ask separately for testing evidence that names the endpoints and the accounts used.

What should a pre-launch API test report contain?

It should name the specific endpoints tested, the accounts and roles used, the dates of testing, and each finding with a severity and current status. It should state explicitly whether authorization was exercised across multiple accounts, since that is the test most often omitted. Retest results after remediation should be included before acceptance.

What contract language helps an agency require API security testing?

Useful terms include an explicit right for the agency or its designee to test the interface, provision of test accounts and a test environment at no added cost, remediation timelines tied to finding severity, and acceptance conditioned on closure of high and critical findings. The scope clause should name machine interfaces, all supported versions, and non-production environments holding agency data. Requirements vary by state and data type, so confirm specific obligations with counsel before finalizing.