Simulate a policy decision

Policy simulation answers “would this exact request be allowed?” against a specific policy version, without affecting live traffic. Use it to validate a change before publishing, or to understand why a real call was denied.

Requires policy.read

Simulation needs read access to policies in the target environment.

Simulate a decision

Provide the principal, action, resource, and context — the same four inputs Cedar evaluates — and get back the decision, the matched rule, and the policy version.

Simulate whether a request is allowed

UIAPICLI

1. Open Access → Policy simulator.
2. Set the user/agent, client surface, environment, server/tool, and credential mode, then run the simulation.
3. The result shows allow/deny, the matched rule, and the policy version evaluated.

POST/v1/policies/simulate

Copy

curl -X POST "$GATEWAY/v1/policies/simulate" \
-H "authorization: Bearer $TOKEN" \
-H "content-type: application/json" \
--data '{
  "user_id": "user_ada",
  "agent": "sales-contract-agent",
  "client_surface": "external-chat",
  "environment": "prod",
  "server": "legal-contract-review",
  "tool": "contract_read",
  "policy_version": "cedar-policy-v3"
}'

View simulatePolicy in the API reference →

Copy

gatewayctl simulate-policy \
--user user_ada --agent sales-contract-agent \
--client-surface external-chat --environment prod \
--server legal-contract-review --tool contract_read \
--policy-version cedar-policy-v3 --format json

Every gatewayctl verb accepts --format text|json.

Diagnose a denial

When a real call is denied, turn its stable machine reason into a human‑readable diagnosis — the matched (or missing) rule, the policy version, and safe context, with no payloads or secrets.

Diagnose why a request was denied

UIAPICLI

1. Open Investigate → Deny diagnostics.
2. Paste the machine reason (or open the denied audit event) to see the diagnosis and the rule that produced it.

POST/v1/deny-diagnostics

Copy

curl -X POST "$GATEWAY/v1/deny-diagnostics" \
-H "authorization: Bearer $TOKEN" \
-H "content-type: application/json" \
--data '{"reason_code": "invalid_auth_context"}'

View createDenyDiagnosticsBundle in the API reference →

Copy

gatewayctl diagnose-deny invalid_auth_context

Every gatewayctl verb accepts --format text|json.

Tip

Simulate the change, confirm the decision flips the way you expect, then publish the policy version. The audit trail will attribute every later decision to that exact version.