DEVELOPER FIELD GUIDE

Good security starts
with a testable decision.

Turn architecture conversations into explicit contracts, negative tests, and useful evidence. Start with one workflow and make the boundary reviewable.

1. Describe the intended behavior.

Before choosing middleware or a vendor, write down which actor may perform which action on which resource. Identify the authoritative source for identity, tenant membership, and ownership. Include the worker or downstream system that performs the action, not only the browser or gateway that receives it.

The reference below is a vocabulary for a design review. It is deliberately not an API Sentinel SDK, endpoint, or executable policy file. Translate the concepts into the components you actually operate and verify their behavior with tests.

reference-policy.yaml

# Illustrative policy vocabulary — not a runnable SDK configuration.
operation: invoice.read
identity:
  require_authenticated_actor: true
resource:
  require_actor_tenant_matches_owner: true
execution:
  authorize_at_resource_boundary: true
evidence:
  record: [operation_id, policy_version, decision, outcome]
  exclude: [authorization_header, request_body, response_body]

2. Test the boundary, not just the happy path.

Expected access

An active member requests a resource in their organization with the required permission. Check both the permitted decision and the expected application result.

Different owner

An otherwise valid caller requests an object from a different tenant. Verify denial before data is returned or a downstream operation is triggered.

Changed context

Membership or resource ownership changes before a queued job executes. Confirm that the implementation follows the intended revalidation policy.

Partial failure

A permitted operation fails in a dependency. Keep the permission decision distinct from the execution result, and prevent an uncontrolled retry loop.

3. Make the evidence proportional.

Define the minimum event fields needed to explain the decision and connect it to its outcome. Use route templates and restricted resource references where possible. Avoid credentials and complete payloads in routine logs. Test malformed events, redaction, delivery failures, and access to the investigation view.

A trace identifier supports correlation; it does not authorize the request. A recorded allow decision does not prove execution completed. A missing usage report is not confirmed zero consumption. Keeping these distinctions explicit prevents monitoring dashboards from reporting more certainty than the system has.

4. Release the change with an owner.

Record the policy version, affected paths, tests, rollout conditions, rollback decision, and incident contact. Review exceptions before they become permanent. Verify legitimate client behavior as well as expected denials. For consequential workflows, rehearse a controlled failure using synthetic data and an authorized environment.

Choose a specific companion guide for the next review. Object-level access, AI agent permissions, and resource budgets have different state and concurrency considerations; one generic security flag cannot replace those decisions.