API object authorization: decide who can act on each record

What is API object authorization?#

API object authorization is the decision that connects an actor, an action and a specific object. Authentication establishes who or what made the request; object authorization determines whether that identity may read, change, export or delete this record. A support agent being allowed to use a case endpoint does not automatically authorize every case. The decision may depend on tenant membership, assignment, ownership, record state or a separately approved administrative relationship.

OWASP describes missing checks on records selected through client input as broken object level authorization. Its API guidance calls for the access decision in every function that uses that input to reach a record. An unpredictable identifier can reduce guessability but does not establish permission. The record may be selected by a path parameter, a nested request field, a search filter or an asynchronous export specification; review the selection behavior rather than looking only for one URL pattern.

Begin by naming the objects with meaningful business boundaries. In a document product, a folder, document, version and export may have different access rules even when they share a workspace. Treating every object as an interchangeable row can hide a permission transition the product team intended to preserve.

Write an access rule before choosing middleware#

An access rule should be explainable as a sentence: an active workspace member may read a document in that workspace unless the document is restricted to its named reviewers. This is a fictional product rule, not a universal model. It exposes the relationships implementation must inspect. A role named operator does not say which workspace the person belongs to, which document they may change or whether their assignment has ended.

OWASP recommends least privilege, denial by default and permission validation on every request. Use those principles to ask what affirmative condition grants the action. Missing tenant context, an unknown action or a failed policy dependency should not accidentally become a grant. Agree the actual failure behavior with the owner, especially where an authorization service is separate from the API and availability pressure might encourage a permissive fallback.

Keep the policy record close to the product decision. A permissions table with an owner and a rationale can be reviewed when a new sharing feature is proposed. Middleware is useful for consistent execution, but it cannot supply the business relationship that was never specified. Changes to the rule should explain which people gain or lose authority and why.

Compare the boundary each control actually enforces#

These controls answer different questions. Select a combination around the product rule rather than treating one implementation layer as a replacement for every other layer. The table is a design comparison for a hypothetical multi-tenant application. Its useful result is an explicit enforcement responsibility, with an owner who can show the corresponding evidence.

Follow the object through every delivery path#

List the ways an object can be reached: direct API reads, updates, lists, search, exports, attachment downloads and background jobs. A control applied only to the visible detail page leaves the product policy fragmented. Agree a shared policy interface or enforcement pattern, then show how each path supplies the actor, requested action and trustworthy object context. Distinguish data supplied by the client from relationships established by the application.

Database row security can support isolation, but its scope depends on the database role and policies. PostgreSQL documents default denial when row security is enabled without an applicable policy; it also documents that superusers and BYPASSRLS roles bypass it, while table owners normally do as well. Review the actual application connection role rather than assuming a policy visible in a migration is effective at runtime.

For a background export, decide whether the job carries a snapshot of an approved decision or rechecks current authority before producing and delivering the artifact. Neither choice is automatically correct for every workflow. A long-running administrative report may need explicit delegated authority, while a member's download may need current membership at retrieval. Record the policy for both creation and consumption so the artifact does not become an unexplained alternate access path.

Include state changes and concurrent decisions#

Object permissions are often time-dependent. A reviewer can be removed, a document can be finalized or a tenant can be suspended between two requests. Specify which changes affect authority immediately and where the application learns about them. A cached role list can remain current while a document assignment has changed; a global user cache and an object relationship cache therefore need separate review.

For a consequential update, consider what happens between policy evaluation and the write. The application should make the relevant state transition consistent with the agreed rule, using the transaction or concurrency mechanisms appropriate to its storage model. A decision against a draft does not automatically justify modifying a record another request has already finalized. The exact mechanism belongs in the design, but the expected conflict outcome belongs in the policy and tests.

Treat derived artifacts as objects too. A link, temporary download token or cached export can persist after the original relationship ends. Choose whether it remains valid under an explicit sharing rule or requires a fresh access decision. This is a product tradeoff about usability and consequence, not a question that the shape of an identifier can settle.

Fictional worked example: an approval API with two workspaces#

This fictional defensive example concerns Ledgerroom, an invented approval application. Workspace Amber and workspace Slate contain only synthetic expense requests. Mina is an Amber member, Theo is an Amber reviewer, and Jo is a Slate member. The agreed policy lets members read their own requests, assigned reviewers read and approve requests in their workspace, and workspace administrators manage membership without automatically gaining approval rights.

The team writes a permission matrix before inspecting the implementation. Mina may read her draft and submit it, but may not approve it. Theo may approve Mina's submitted request only while the assignment is active. Jo may use the same API features for Slate records but must not receive Amber content. Unknown relationships produce denial. The matrix also identifies the allowed fields: an assigned reviewer needs the expense evidence, while a general workspace summary does not need private receipt details.

Review finds that direct reads use an object policy but the export job relies on a role name captured when the job was queued. The hypothetical defect is not demonstrated with customer data. The team creates a synthetic Amber request, queues a reviewer export, removes Theo's assignment, and runs the job in the owned test environment. Under the chosen product rule, Theo's export should omit that request and its receipt because delivery requires current assignment.

The proposed correction makes the worker obtain current relationships and apply the approved export action policy. The artifact download path also checks the recipient's current authority. Tests cover a retained assignment, a removed assignment, a Slate identity and an unknown record. Evidence includes the permission rule version, sanitized job result and fixture state. The legitimate reviewer export must still succeed, so the fix is evaluated for correctness as well as denial.

The owner explicitly distinguishes workspace administration from expense approval. A recovery operation can reassign a request but cannot silently approve it. This exception receives its own audit event and test case. The final handoff says which API and worker paths enforce the matrix, which database role they use, and which shared-link behavior remains outside this review. The example illustrates a review method; it does not claim a deployed product or an actual security finding.

Make denied outcomes part of the verification plan#

OWASP's authorization testing guidance describes a matrix connecting roles, features and relevant data, then using it to drive integration tests. Adapt that structure to the application relationships your team actually maintains. The matrix should express the expected rule independently of the implementation so a test failure causes review instead of an automatic update to match current behavior.

For each grant, test the closest meaningful denial: another tenant, a former assignee, a different action or a restricted state. Verify the response and the side effects. A denied update that still queued a job has not satisfied the intended boundary. For lists and exports, inspect synthetic contents rather than relying only on a successful status code. Maintain a small readable core of high-consequence cases, then add combinations that reflect the application's actual risks.

• Use owned accounts and fixtures with explicit tenant, owner, assignment and state relationships.
• Verify an allowed case and the closest denied case for each important action.
• Inspect direct reads, mutations, lists, search, downloads and background exports.
• Confirm denied operations expose no protected fields and create no unauthorized side effects.
• Change membership, assignment and record state, then verify the expected fresh decision.
• Run the tests through the real application database role and policy configuration.
• Record the policy version, application revision and untested paths in the result.

Keep exceptions narrow and decisions observable#

Administrative support and recovery workflows need an explicit policy, not an undocumented bypass. Name the permitted action, scope, approver and audit requirement. If support can view a customer's document for a limited task, specify whether consent or delegated approval is required and when access ends. An exception that cannot be explained is difficult to review when the product changes.

Log a useful decision reference rather than the record body. An operational event can include the action, policy version, actor reference, object reference and result classification, subject to the application's privacy requirements. Correlate it with the request or job so an engineer can distinguish a legitimate denial from a broken relationship lookup. Monitor changes in behavior without turning every ordinary denied request into an incident.

Hand over a maintained access decision#

The useful deliverable is a policy the next engineer can explain, an enforcement map and evidence for the important allowed and denied combinations. Include the object relationships, exception owner, cache or propagation assumptions and paths still outside coverage. A sentence claiming that the API is secure obscures precisely the details a future change will need.

Start with one consequential object and trace its full lifecycle. Agree the rule with the product owner, inspect the implementation, verify owned fixtures and add regression cases for the important boundary. Use a scoped assessment record when behavior must be investigated across services. Expand to the next object because its consequence warrants review, keeping each conclusion proportional to what was actually checked.