Identify API assets and actors

An API exposes application capabilities directly. Before you pick a single security control, list what callers can read, change, trigger, or spend. That list is the map every later decision depends on.

List the actors

Include anonymous callers, users, administrators, mobile apps, background jobs, partners, and third-party services. Each one authenticates differently and deserves different limits.

Here is a starting point for an invoices API:

actors:
  - name: customer
    auth: session cookie or OAuth token
    operations: [list own invoices, download own PDF]
  - name: support-staff
    auth: SSO with staff role
    operations: [search invoices, issue refunds]
  - name: accounting-job
    auth: scoped API key, runs nightly
    operations: [export all invoices]
  - name: payment-provider
    auth: signed webhook
    operations: [mark invoice paid]

For each actor, record the intended operations and sensitive data. This becomes the authorization and testing map.

Attach impact to each operation

Not every operation carries the same risk. Record data sensitivity and maximum loss beside each operation:

GET  /invoices/:id         customer data       loss: one record leaked
POST /invoices/:id/refund  money movement      loss: unbounded without a cap
GET  /exports/invoices     all customer data   loss: the full dataset

That evidence separates a harmless invoice search from a refund path that needs stronger approval, logging, and recovery controls. A support account that can issue refunds turns a useful integration into a money-moving security boundary.

Test the map with a compromised actor

A good map answers a concrete question: what happens if this actor is compromised? Pick the support role and walk the table with its real credentials:

curl -i -X POST https://api.example.com/invoices/inv_00193/refund \
  -H "Authorization: Bearer $SUPPORT_TOKEN" \
  -d '{"amount": 490000}'
# HTTP/1.1 403 Forbidden — refunds above the per-day cap need approval

If the honest answer is “a stolen support token can refund every invoice, with no cap and no alert”, the map found your first real risk before you wrote any code. That is the point of doing this first.

Revisit the table when a new integration lands. Most scope creep arrives one “quick partner endpoint” at a time, and the map only helps while it matches what production serves.

Create an actor-to-operation table for the invoices API. Prove it is useful by adding a compromised support account and recording which reads, writes, and refunds must fail.