Authorize Bulk APIs Without Leaks or Partial Corruption

Bulk authorization semantics should follow the operation’s disclosure and atomicity requirements. Filter unauthorized objects for discovery-style reads when omission is normal; return per-item outcomes for independent jobs; fail the entire request for mutations that must preserve an invariant. Never let a bulk wrapper weaken the authorization required by the equivalent single-object operation.

Decide by operation, not endpoint shape

A bulk read used to populate a dashboard can omit unauthorized objects if callers already expect a partial visible set. An explicit lookup of ten supplied IDs may need a uniform not found result for missing and unauthorized items to avoid confirming existence. We generally recommend failing exports closed if any requested scope is unauthorized, because a partial archive can be mistaken for complete and counts may leak hidden records.

For writes, ask whether items are one business transaction. Moving funds between accounts, changing a policy and its bindings, or replacing a complete membership set should be atomic: authorize every intended effect against one consistent state, then commit all or none. Independent email preference updates may return per-item outcomes. Document that partial success is possible and give every item a stable correlation key.

The OWASP Authorization Cheat Sheet distinguishes authorization from authentication and recommends both least privilege and deny-by-default decisions. A batch endpoint still contains many object requests, so check action, resource, tenant, and relevant attributes for every item, even when the caller has a broad role. Cap batch size so authorization checks and transactions cannot become an availability problem.

Make the response unambiguous

For independent items, return a top-level request ID and an ordered or keyed result for each submitted item: succeeded, invalid, conflict, unavailable, or not found. Avoid a separate forbidden state when that would reveal object existence. Include a retryable flag only when the server knows retry is safe. Do not return sensitive authorization explanations to the caller; keep detailed policy reasons in protected logs.

RFC 9110: HTTP Semantics supports a narrower point than many API design summaries: HTTP is a stateless request/response protocol with a uniform interface, and a request can be considered in isolation. That supports making batch-envelope behavior explicit in your contract instead of assuming clients will infer it from HTTP alone. In our recommendation, a 200 can be acceptable for a syntactically valid batch request that returns per-item outcomes, provided your API defines that contract clearly. A malformed envelope or unauthenticated request can still fail at the top level before item processing.

Use idempotency keys for bulk mutations whose retry could repeat effects. Bind the key to the caller, tenant, operation, and a hash of the normalized item set. Reusing the key with different input should fail. Persist the final per-item result so a timeout followed by retry returns the same answer. Idempotency does not repair non-atomic business logic; each item still needs transaction or compensation boundaries.

Recheck before commit

Do not authorize the first page, queue a long job, and assume permission lasts forever. Store the initiating subject and scope, then define whether execution uses current authorization or a captured grant. For sensitive exports and delayed mutations, consider rechecking authorization at execution time and before result retrieval. If permissions change halfway through an independent batch, stop remaining work or record per-item denial according to the published contract.

Audit the batch and each effect with subject, tenant, action, resource, decision, idempotency key, and correlation ID. The OWASP Authorization Cheat Sheet notes that poor access-control logging can leave violations undetected or unattributable, which supports recording authorization decisions alongside the business effects they gated. Keep results retrievable for a bounded period without making the status endpoint a new data leak. Authorize cancellation and status reads separately.

Test mixed outcomes

Include all allowed, all denied, one denied among allowed, duplicate IDs, cross-tenant IDs, concurrent revocation, retry after timeout, and failure after some commits. Assert database state, response shape, counts, and audit records. Verify timing and totals do not reveal how many hidden objects existed.

Reviewed: 2026-09-06

The next step is to classify each existing bulk endpoint as filtered read, atomic transaction, or independent item batch, then add one mixed-authorization test. Review by 2026-12-05 or when its business invariant changes.