# Pattern: Object-Level Authorization Check

Status: draft
Readiness target: RL3 production
Primary owners: flex-auth, product repos, NetKingdom

## Problem

APIs often authenticate callers correctly while still allowing access to
objects, records, files, or tenant resources outside the caller's scope.

## Context

Use this pattern for product APIs, admin APIs, object storage brokers,
artifact-store, tenant data, background jobs, and any endpoint that
accepts resource identifiers.

## Forces

- Object ownership and scope are application-specific.
- Authorization must happen before data is returned or mutated.
- Tenant context must be trusted, not copied from user input.
- Bulk, search, and background operations need the same checks.

## Solution

Require every object access path to ask an authorization boundary with
trusted actor, tenant, resource, action, and context before reading,
writing, deleting, exporting, or sharing an object.

## Implementation Sketch

1. Define resource types and action vocabulary.
2. Derive actor and tenant from trusted identity/session evidence.
3. Resolve object ownership or scope before access.
4. Ask flex-auth or local policy adapter for a decision.
5. Enforce allow/deny before data access.
6. Log object-level decisions with correlation ids.

## Failure Modes

| Failure | Mitigation |
| --- | --- |
| Endpoint checks role but not object ownership | add object-level conformance tests |
| Search/list endpoints bypass item checks | enforce tenant/resource filters in query layer |
| Background jobs run with global authority | carry tenant and actor context in job envelopes |
| Deny reason leaks object existence | use stable, non-revealing deny responses |

## Related Capabilities

- Application and API security.
- Authorization and access control.
- Tenant isolation.
- Data protection and privacy.

## Maturity

Draft. The pattern maps directly to flex-auth but requires product-level
adoption and tests.

## Verification

- Cross-tenant object access tests fail.
- List/search endpoints cannot reveal out-of-scope objects.
- Background jobs preserve authorization context.
- Deny paths are audited and do not leak sensitive existence details.

## Research Basis

Seeded by API authorization, object-level authorization, OWASP API
security framing, and tenant-scoped authorization.

## References

- Initial exploration: Application and API security.
- Initial exploration: Application/API patterns.