API Abuse and Data Scraping Response Playbook

When someone has pulled millions of records out of an API or a public-facing feature, the hardest questions are not technical: what exactly left, about whom, and does it count as a breach that must be reported. This playbook template covers the response once bulk API abuse or scraping is suspected or confirmed: intake, triage, containment that does not destroy evidence, scoping exposure down to fields and individuals, the notification decision, recovery and review. It is built on the GDPR definition of a personal data breach, regulator statements on scraping, the OWASP API Security Top 10 2023 and published incidents such as the T-Mobile API breach. It is written for incident managers, API and platform owners, privacy officers and legal counsel. Prevention is covered in the Rate Limiting and API Abuse Guide and the Web Scraping Defence Guide; this page starts where they stop. Adapt the bracketed text before adoption.

How to use this template

Replace text in square brackets, such as [Organisation], [Incident Manager], [Privacy Officer], [API Gateway] and [SIEM], with your own names. "Must" is mandatory; "should" is recommended.
Decision points are marked D1 to D4. Record each decision, who made it, when and the evidence it rested on, using the Incident Log and Decision Record Template.
Set severity with the Incident Severity Classification Matrix Template. This playbook sits under the Incident Response Plan Template. Where the abuse is password guessing against a login API, use the Credential Stuffing Attack Response Playbook instead.
Timings marked as NHI Mgmt Group recommendations are starting points, not legal deadlines.

1. Purpose and scope

1.1 This playbook applies when [Organisation] has reason to believe that an API, a public web feature (search, contact import, profile lookup, export) or a partner integration has been used to extract data at a scale or in a way that [Organisation] did not intend.

1.2 It covers three situations, which often overlap:

Authorisation flaw: a caller retrieved objects or fields it was not entitled to, for example by changing identifiers (OWASP API1:2023 Broken Object Level Authorization) or receiving excessive properties (API3:2023 Broken Object Property Level Authorization).
Abuse of an intended flow: a caller used a permitted feature at a volume or pattern that turns it into bulk collection, for example matching phone numbers or email addresses to profiles (API6:2023 Unrestricted Access to Sensitive Business Flows, API4:2023 Unrestricted Resource Consumption).
Abuse of legitimate credentials: a partner, customer or compromised account used valid API keys or tokens to harvest data beyond its purpose.

1.3 Out of scope: denial-of-service response and fraud losses, which follow their own playbooks, except where they accompany data extraction.

2. Roles

Role	Responsibilities
[Incident Manager]	Owns the incident, chairs decision points, keeps the timeline
[API Owner] and [Platform Engineering]	Explain intended behaviour of the endpoint, apply containment, produce logs and schema
[Security Operations]	Detection, log analysis, attribution of callers, indicators
[Privacy Officer] or DPO	Personal data assessment, breach determination, regulator liaison
[Legal Counsel]	Notification duties by jurisdiction and contract, privilege, law enforcement, takedown requests
[Communications]	Customer, media and public statements, coordinated with legal
[Partner Manager]	Where a partner credential or integration is involved, contact and contractual steps

3. Triggers and intake

3.1 Any of the following must open an incident ticket and page [Security Operations]:

Telemetry: request volume, distinct object identifiers or response bytes per client, key or token above baseline; sequential or enumerated identifiers in request paths; high 404 or 403 ratios followed by 200s.
External claim: a dataset offered on a forum or leak site that matches [Organisation] fields, a journalist or researcher enquiry, or a regulator contact.
Researcher report: a vulnerability disclosure describing an authorisation flaw on a data-returning endpoint.
Customer or partner report: unexpected contact from people who say their data was used.

3.2 A dataset claim must be treated as a trigger even if no internal alert fired. Many scraping incidents are first noticed when the data is offered for sale.

4. Triage and classification

4.1 Within [4] hours (NHI Mgmt Group recommendation), [Security Operations] and [API Owner] must answer the triage questions below and record the answers.

Question	Why it matters	Evidence
Which endpoint or feature, and is it authenticated?	Defines who could have called it and how many records it can return	[API Gateway] route logs, API inventory entry
Did any caller receive data it was not authorised to see?	Separates an authorisation flaw from abuse of an intended flow	Authorisation decisions in logs, code review of the handler
Which fields were returned, including fields not shown in the user interface?	Excessive properties often turn "public" data into non-public data	Response schema, sample responses from logs or replay in test
Which credentials or clients made the calls?	Drives containment and attribution	API keys, OAuth client IDs, account IDs, IP addresses, user agents
When did it start and is it still running?	Sets the exposure window and urgency	Earliest anomalous request, current request rate
Does a dataset exist outside [Organisation]?	Raises likelihood of harm and public attention	Threat intelligence, sample provided by claimant

4.2 D1, classify: authorisation flaw, abuse of intended flow, abuse of legitimate credentials, or not an incident (expected use). Record the reasoning. Classification may change as scoping proceeds.

5. Containment

5.1 Containment must stop further extraction while preserving the evidence needed to scope it. Before changing anything, export and preserve gateway, application and WAF logs for the full suspected window (see section 9).

5.2 Options, from least to most disruptive:

Block or throttle identified clients: revoke the specific API keys or tokens, block source addresses and autonomous systems, add the client fingerprints to the bot management deny list.
Tighten limits on the affected route: per-client and per-identity caps on objects returned, pagination limits, lower burst limits. See the Rate Limiting and API Abuse Guide for the mechanics.
Remove excess fields from responses or require additional authentication for the feature.
Disable the feature or endpoint until a fix is deployed.

5.3 D2, disable or degrade: [Incident Manager] decides with [API Owner] whether to disable the feature. Disable when an authorisation flaw is confirmed and exploitation continues; degrade when the flow is intended and abuse can be contained by limits. Record expected customer impact.

5.4 Where a partner credential is involved, [Partner Manager] must notify the partner, suspend its access and request its own logs. Partner API keys are machine identities: revoke the specific key rather than the whole partner programme where possible.

6. Scoping exposure

6.1 Scoping must produce numbers that a regulator, a court and a journalist would accept. Work from logs, not from estimates of what the endpoint could return.

Measure	How to derive it	Common error
Requests and successful responses by client	Gateway logs grouped by key, token, account and source	Counting only the blocked requests
Distinct records returned	Distinct object identifiers in successful responses	Counting requests instead of distinct records
Distinct individuals affected	Map records to people; deduplicate people with several records or accounts	Reporting accounts as people
Fields exposed per record	Response schema in force during the window, including hidden properties	Listing only fields visible in the interface
Sensitivity of combined fields	Assess the combination: a phone number matched to a name and profile is more harmful than either alone	Treating each field as public in isolation
Exposure window	First to last anomalous successful request, plus retention gaps	Starting the window at detection

6.2 If logs do not cover the full window, state the gap and give a reasoned upper bound. Do not report the logged figure as the total.

6.3 In the T-Mobile API Breach 2023, unauthorised API access reportedly began around 25 November 2022 and was detected on 5 January 2023, about six weeks later. The company's disclosure listed both the fields exposed (name, billing address, email, phone number, date of birth, account number, lines and plan features) and the categories the API could not return, which is the precision customers and regulators need.

7. Notification decision

7.1 D3, is it a personal data breach? Under GDPR Article 4(12) a personal data breach is a breach of security leading to the accidental or unlawful destruction, loss, alteration, unauthorised disclosure of, or access to, personal data. An authorisation flaw that let callers read other people's records meets that test on its face. Abuse of an intended flow is harder: assess whether the security of the feature was breached by design or configuration, as well as whether each field was available to some audience.

7.2 Regulators have addressed scraping directly. In an August 2023 joint statement by twelve data protection authorities, the UK ICO said mass scraping incidents "may require reporting to the ICO as a personal data breach." In November 2022 the Irish Data Protection Commission fined Meta Platforms Ireland 265 million euros for infringing GDPR Articles 25(1) and 25(2), data protection by design and by default, in an inquiry into Facebook Search and the Facebook and Instagram contact importer features after a scraped dataset appeared online. The lesson: "the data was public" is not, on its own, a defence.

7.3 Where GDPR applies, the controller must notify the supervisory authority without undue delay and, where feasible, not later than 72 hours after becoming aware of a personal data breach, unless it is unlikely to result in a risk to individuals (Article 33), and must tell affected individuals without undue delay where the breach is likely to result in a high risk (Article 34). A processor must tell the controller without undue delay.

7.4 For other jurisdictions, [Legal Counsel] must check each applicable law: US state breach laws turn on their own definitions of personal information and breach, which often require specific data elements such as account credentials or government identifiers. Use the Data Breach Notification Checklist and the Breach Notification Laws by Country Guide. Confirm against the official text before relying on it.

7.5 D4, notify whom: record the decision for each audience:

Regulators: notify, or document why notification is not required, with the risk assessment attached.
Individuals: notify where risk is high, with specific advice (expect targeted phishing using the exposed fields; how to spot impersonation).
Business customers: where [Organisation] processes data for them, notify as a processor under the contract clock. See the SaaS Provider Incident Notification Guide.
Platforms hosting the dataset: request takedown through [Legal Counsel].
Law enforcement: where extraction was criminal or extortion is attempted.

7.6 A decision not to notify must be documented with the same rigour as a decision to notify, because a regulator may review it later.

8. Eradication and recovery

8.1 Fix the root cause, not only the abused route:

Enforce object-level authorisation in the handler for every request, and test sibling endpoints that share the same pattern.
Return only the fields each consumer needs; remove internal and unused properties from responses.
For sensitive lookup flows such as contact matching, add per-identity quotas, friction and monitoring for distribution of queried identifiers.
Issue each partner and client its own credential and scope; retire shared keys.
Add the endpoint to the API inventory with owner, data classification and limits. See the API Inventory Template.

8.2 Re-enable a disabled feature only after the fix is tested against the abuse pattern seen in the logs, using the API Security Testing Plan Template, and monitoring alerts are in place.

9. Evidence to preserve

Gateway, application, WAF and bot management logs for the window, with hash values and storage location recorded.
The response schema and code version in force during the window.
Client registration records for every key, token and account involved.
Copies or samples of any dataset offered externally, collected through [Legal Counsel].
All decision records for D1 to D4 and the scoping calculations.

Keep chain of custody for anything that may support legal action. See the Evidence Handling and Chain of Custody Guide.

10. Post-incident review

10.1 Within [20] working days of closure (NHI Mgmt Group recommendation), hold a review that answers: why existing limits and monitoring did not stop or flag the extraction earlier; which other endpoints share the same flaw or flow; whether the API inventory was complete; and whether the notification decision was made within the required time.

10.2 Track actions to closure with owners and dates.

Implementation guidance

Before the next incident. Make sure the data you need for section 6 exists: log the client identity, object identifiers and response size for every data-returning API call, and keep those logs for longer than your typical detection delay. Maintain an inventory of endpoints that return personal data, with field lists. Pre-agree the D3 assessment method with the [Privacy Officer] so it is not invented under pressure.

Rollout. Phase 1: run the triage and scoping queries against one high-volume endpoint in a test and confirm you can produce distinct record and individual counts. Phase 2: tabletop an external dataset claim using the Tabletop Exercise Scenario Pack. Phase 3: automate the per-client volume alerts and attach this playbook to them. Containment changes in section 5 should be deployable as configuration with a documented rollback, so a mistaken block can be reversed in minutes.

Small and large organisations. A small organisation can run this with one incident lead, the developer who owns the API and outside counsel, and should focus on log retention and the notification decision. A large organisation should pre-assign API owners, keep scoping queries in the SIEM and give the privacy team direct log access.

Metrics. Time from first anomalous request to detection; time from detection to containment; percentage of data-returning endpoints with per-client volume alerts; percentage of endpoints in the inventory with field lists; time from awareness to the D3 decision.

Framework mapping.

Playbook step	NIST CSF 2.0	NIST SP 800-53 Rev. 5	OWASP API Security Top 10 2023
Detection and intake	DE.CM-01, DE.AE-02, RS.MA-02	SI-4, AU-6	API4, API6
Scoping	RS.AN-03	AU-6	API3
Containment and eradication	RS.MI-01, RS.MI-02	AC-3, SC-5	API1, API3, API9
Notification	RS.CO-02	IR-6	Not covered

In MITRE ATT&CK terms, bulk extraction through an application maps most closely to T1119 Automated Collection and T1213 Data from Information Repositories; use these labels for reporting, not as a detection strategy.

Standards and references

This template summarises notification considerations for practitioners and is not legal advice. Related NHI Mgmt Group resources: API Security Guide · Bot Management Guide · Web Scraping Defence Guide · SaaS Provider Incident Notification Guide

API Abuse and Data Scraping Response Playbook: Scoping Exposure and Deciding Whether to Notify