On this page
Start with one workflow
Choose a useful, bounded operation rather than attempting to redesign the whole platform at once. A private document download, a report export, or a read-only AI assistant makes a practical starting point. Write one sentence describing the legitimate task and one sentence describing the most important outcome that must not occur.
For a report export, the task might be “a project member exports reports they are allowed to read.” The unacceptable outcome might be “the job exports another tenant’s documents.” These statements give the design a concrete resource and permission boundary.
Step 1: draw the real path
Trace the caller, public endpoint, gateway, application, data store, worker, and result download. Include any model or external provider. Add alternate hostnames and administrative paths. Identify where credentials are verified and where current resource permission is evaluated.
Do not stop at request acceptance. A queued task and a completed artifact can outlive the user’s session or membership. Mark where the design must reevaluate access. The API shield architecture guide explains why these transitions deserve separate decisions.
Step 2: write the permission matrix
Name the actors, resources, and operations. Include two tenants, a read-only member, a user who belongs to multiple projects, a revoked membership, and a service integration. State which combinations should succeed and which should fail.
Build fixtures for both response behavior and protected state. A denied request should not queue work or change a record first. Check list and bulk operations separately. Use the API security release guide to connect this matrix to review evidence.
Step 3: specify the request contract
Document the method, route, content type, required values, permitted fields, and size boundaries. Identify values that multiply work, including array lengths or export ranges. Keep the contract with accepted and rejected fixtures.
Verify the deployed validator’s supported features and configuration. A schema-valid request is not automatically authorized; keep those checks separate. The OpenAPI rollout playbook covers observation, compatibility review, and narrowly scoped enforcement.
Step 4: bound the task
Define the relevant request, concurrency, time, and downstream-work limits. For an AI operation, include tokens, retries, retrieval depth, and tool steps. Choose values based on the actual workload and make the source of each value reviewable.
Decide when a reservation expires and how cancelled or failed work is reconciled. A worker restart should not silently reset an unlimited retry budget. Read the rate limiting and AI budgets guide for a complete unit-of-work approach.
Step 5: define uncertain and failed states
Write the behavior for unavailable authorization, quota, classification, and logging dependencies. Sensitive operations should not become unconditionally allowed because a check is slow. A lower-risk degraded mode needs its own explicit restrictions.
For a model-assisted task, separate classifier signals from independently enforced authority. Treat generated tool calls as proposals. The AI shield architecture and LLM boundary guide show how to keep the application in control when a model’s interpretation is wrong.
Step 6: run a release and incident exercise
Walk a normal request, a cross-tenant request, an oversized job, a stale permission, and a dependency outage through the design. Record the expected decision, actual side effects, user-visible result, and minimized event evidence.
Then rehearse one containment action: disable an integration, restrict a tool, or roll back a bad contract rule. Confirm that the team can identify the responsible owner and restore the intended boundary. The logging and response playbook helps distinguish attempted actions from completed outcomes.
The deliverable: a small, testable decision record
Finish with the workflow diagram, permission matrix, contract fixtures, work budgets, failure rules, and operational owner. Keep them near the feature code or configuration so ordinary changes trigger a review. Record unresolved risks and scoped exceptions rather than hiding them in a general “security complete” label.
Use the security checklist for the release conversation. Return to the record when adding a route, a data connector, a model, or a tool. The first useful shield is a boundary your team can explain and reproduce.