Identify API assets and actors

Before you pick a single security control, write down what your API lets people do. Who can call it, what they can read, what they can change, what they can spend. That list is the map. Every decision in this course comes back to it.

I know it sounds like paperwork. It’s the opposite. It’s the fastest way to find the risk that matters, before you write any code.

List the actors

An actor is anyone or anything that sends requests to your API. Anonymous visitors, signed-in users, admins, a mobile app, a nightly job, a partner, a payment provider. Each one authenticates in a different way and deserves different limits.

We’ll use an invoices API as the running example for the whole course. Here’s how I would start its actor list:

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, note the operations it should be able to run and the sensitive data it touches. Later this becomes your authorization rules and your test plan.

Attach impact to each operation

Not every operation is equally dangerous. Next to each one, write the kind of data involved and the worst thing that can happen:

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

Now you can see the difference between a harmless invoice search and a refund path that needs approvals, logging, and a way to recover. A support account that can issue refunds is not “just an integration”. It moves money, so it’s a security boundary.

Test the map with a compromised actor

A good map answers one concrete question: what happens if this actor gets compromised?

Pick the support role. Imagine someone stole a support token. Walk the table with that token and check what the API does:

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

That 403 is what you want. If the honest answer is instead “a stolen support token can refund every invoice, with no cap and no alert”, you found your first real risk. And you found it before writing a line of code. That’s the whole point of doing this first.

One more thing. Revisit the table every time a new integration lands. Scope creep arrives one “quick partner endpoint” at a time, and the map only helps while it matches what production serves.

Try this on your own API: build the actor-to-operation table. Then add a row for a compromised support account and mark which reads, writes, and refunds must fail. If you can’t fill that row in, the map is not done yet.