secure-api-endpoint

---
name: secure-api-endpoint
description: Use when adding or modifying an API endpoint by hand (route, handler, serializer, validation, authorization policy). Applies the two-layer auth model, public-identifier-only exposure, tenant-safe persistence and the input, query, upload and log checklist.
---

# Secure API endpoint

## Required context

1. `.agents/areas.json`: the area the endpoint lives in, its guardrail and its `verify` command.
   For service code the guardrail is `.agents/guardrails/code-style.md` until the adopter adds a
   dedicated API rulebook; if one is declared, it wins.
2. `.agents/guardrails/data-handling.md`: logs, PII, exposure.
3. `.agents/skills/tenant-safe-change/SKILL.md`: when the endpoint reads or writes tenant data.
4. The **sibling endpoint** closest to yours: its route, handler, serializer, validation and
   tests. The sibling is the convention in force.

For an endpoint generated from a schema, use `.agents/skills/api-code-generation/SKILL.md`
instead; for its tests, `.agents/skills/api-test-generation/SKILL.md`.

## The rules that bite

- **Two layers, both present.** Authentication middleware establishes identity; the handler
  **authorizes the action** as its first step, before any query with side effects. A route being
  authenticated is not the same as the caller being allowed, and the gap is where cross-account
  access lives.
- **One authorization source.** Register the new permission in the permission matrix the codebase
  already uses. An inline role check is a second mechanism that drifts from the first.
- **List endpoints scope the query** to what the caller may see, rather than checking a blanket
  "may list everything" permission and returning the table.
- **Expose public identifiers only.** Never the internal sequential or sortable id (it leaks
  volume and enables enumeration), never tokens, password hashes or secrets.
- **One versioned route prefix**, identical in routes, tests and clients. Register a literal
  segment before a parameter route of the same prefix, or the parameter swallows it.
- **Validate every writable field.** Clamp every page-size parameter to a hard maximum, because an
  unbounded page is a denial-of-service parameter.
- **Escape pattern-matching input** (LIKE wildcards), and **bind raw SQL parameters**, never
  concatenate.
- **Uploads** check type against an allowlist; never allow active content (SVG, HTML) without a
  reviewed reason, because it executes in the browser of whoever opens it.
- **Throttle public mutations.** Every unauthenticated write route carries a rate limit.
- **Log without secrets.** No password, token or key in a new log line.
- **Errors use the shared envelope.** A new ad-hoc error shape breaks every client that parses
  errors generically.

## Steps

1. Confirm the resource's database connection and tenancy from the sibling model.
2. If it touches tenant data, follow `.agents/skills/tenant-safe-change/SKILL.md` first.
3. Write handler, serializer, validation, policy and route following the sibling's shape.
4. Write tests that assert authorization denial for the wrong role, validation failure, and the
   happy path, using the same URL prefix clients use.

## Verify

```bash
<the area's test runner, filtered to the new test class>   # fastest proof first
make verify                                                 # every gate, including tools/check-secrets.sh
```

Then the area's `verify` command exactly as `.agents/areas.json` declares it. Reviewers:
`api-standards-reviewer`, `security-data-reviewer`, and `tenant-safety-reviewer` for tenant data.

## Escalate when

- The change alters the authentication or authorization model itself, not just a permission.
- A public contract breaks: a field removed or renamed that clients read, a status code changed.
- A new dependency is needed (`.agents/policy/model-policy.md` treats it as an escalation).
- The endpoint exposes confidential data classes (`.agents/policy/data-classification.yml`) to a
  caller class that did not see them before.