Gateway
Gateway policy simulator
Explain an authorization result before risking a real connector action. The simulator evaluates the same actor, action, payload, environment, and risk context without executing the connector.
On this page
Start here
Use the policy simulator to understand a gateway decision without connector side effects. It evaluates actor, connector, action, payload, and risk, then explains the grants, policies, conditions, reviewers, or freeze behind the result.
Before you begin
- Workspace owner or admin access to the simulator
- A connector plus the real actor and action identifiers you intend to evaluate
- Representative payload, environment, amount, and risk values for the scenario
Put it into practice
-
Model the intended action
Choose the connector and actor, enter action_name, and provide the same contextual values the live call would carry. Avoid a simplified payload that bypasses the condition you need to test.
-
Run without execution
Submit the console form or operator API request. The simulator returns a decision and explanation but never invokes the connector.
-
Follow the decision path
Inspect matched grants and policy, matched and unmatched conditions, reviewer roles, and freeze_reason. Change one input at a time to explain why the decision changes.
The simulated result matches the intended authorization rule, its explanation names the decisive grant, policy, condition, or freeze, and no external connector action occurred.
01 Console
details/app/gateway/simulator
Choose connector_id, actor_type (user or service_agent), action_name, optional payload JSON, and advanced environment, risk_score, and amount. The result shows decision, matched grants, and explanation.decision_path.
02 API body
detailsNot an opaque map
POST /api/v1/operator/policy_simulations takes its fields inside a simulation object, e.g. {"simulation": {"action_name": "send_email", "connector_slug": "email-smtp"}}; a body without that object (or with a non-object simulation) returns 400 invalid_simulation_payload. Inside it the endpoint reads action_name or action (required), connector_id or connector_slug, actor_type=service_agent plus service_agent_id, payload, environment, amount, and risk_score. Missing action returns invalid_action_name. actor_type service_agent without a valid, workspace-owned service_agent_id returns invalid_service_agent; an unknown connector reference returns not_found. Response: decision, connector, matched_grants, matched_policy, matched_conditions, unmatched_conditions, reviewer_roles, explanation (including decision_path and freeze_reason). Owner or admin membership is required (403 admin_required).
Troubleshooting
- The response says invalid_action_name
- Provide action_name or action with a nonempty supported value. The request is a defined schema, not an arbitrary opaque map.
- A service-agent simulation is unexpected
- Set actor_type to service_agent and include the correct service_agent_id: with actor_type service_agent, a missing, malformed, or unknown/foreign service_agent_id returns 400 invalid_service_agent; the simulator never falls back to simulating as the signed-in user. A connector_id/connector_slug that does not resolve in the workspace returns not_found. Recheck environment, amount, risk_score, and nested payload conditions.
- The simulator denies everything
- Look for decision_path frozen before editing grants. A freeze short-circuits policy evaluation, so no policy change can override it.