Policy studio

The Policy studio screen lets you write a Rego or builtin policy, test a Policy Contract request against the active policies, simulate the edited policy, and compare the fields and the decisions of two revisions. Portal path: /studio/policies. It is used by security officers and tenant administrators who write policies, and by developers who test them.

What the screen shows

• On the left, the list of the policies (GET /v1/policies), paginated, with New on top. An empty list shows No policy yet.
• Tabs Editor, Test request and, once a saved policy is open, Revisions (with their number).
• Editor: Name, Engine (opa (Rego) or builtin), Status (Draft, Active, Disabled), Version, then the Rego editor (engine opa) or Rules (JSON) (engine builtin). The starter policy new-policy denies by default and allows model.invoke when the subject holds the scope models:invoke.
• Test request: a JSON editor checked against the request part of the policy-contract contract, prefilled with a sample request (agent subject, model resource, action model.invoke, context). The evaluation result shows Allow or Deny and its JSON; the simulation shows the badges Inputs, Changed, Allow to deny, Deny to allow.
• Revisions: a table with Revision, Change, Version, Status, Date (GET /v1/policies/{policy_id}/revisions). Click two rows: the line From revision a to revision b, the field diff (GET /v1/policies/{policy_id}/revisions/diff) and the decision comparison table (#, First revision, Second revision, Change with Changed or Same).

Actions

Button or action	What it does	API call	Roles
New	Loads the starter policy new-policy.	None	Everyone
Click a policy in the list	Opens it in the editor.	None (row of GET /v1/policies)	Every signed in user of the tenant
Create	Creates the policy.	POST /v1/policies	tenant_admin, security_officer
Save as a new revision	Replaces the policy; an immutable revision is appended.	PUT /v1/policies/{policy_id}	tenant_admin, security_officer
Evaluate with the active policies	Evaluates the request with the active policies of the tenant.	POST /v1/policies/evaluate	Every signed in user of the tenant
Simulate the edited policy	Runs the request with the edited policy as candidate (and up to 20 recorded decisions).	POST /v1/policies/simulate	tenant_admin, security_officer, developer
Click a row of Revisions	First click sets the first revision, second click the second one; the field diff is read.	GET /v1/policies/{policy_id}/revisions/diff	tenant_admin, security_officer, auditor, developer
Compare the decisions of the two revisions	Simulates both revisions on the same request and compares the decisions.	POST /v1/policies/simulate (twice)	tenant_admin, security_officer, developer

Roles

The portal enables the save button for POLICY_WRITERS (tenant_admin, security_officer) and shows Saving requires the tenant_admin or security_officer role. otherwise; it enables simulation and comparison for POLICY_SIMULATORS (tenant_admin, security_officer, developer, also ROLES.policySimulators in portal/src/lib/kit.ts). The Control Plane checks the same lists in services/control-plane/src/eai/domains/policies/__init__.py: ADMIN_ROLES for create and update, ADMIN_ROLES plus developer for simulate, ADMIN_ROLES plus auditor and developer for revisions and diff.

Typical tasks

Write and test a new Rego policy

1. Start from the template. Click New. Expected result: new-policy, engine opa, status Draft. If it fails: reload the page.
2. Write the rule. Keep the deny by default. Edit the Rego editor. Expected result: the Rego text. If it fails: nothing is checked before the save.
3. Simulate. You see the effect before it is active. Open Test request, adapt the sample request and click Simulate the edited policy. Expected result: the badges with the changed decisions. If it fails: simulation_engine_unsupported means the engine cannot be simulated.
4. Create as draft. Click Create. Expected result: the toast Policy saved: a new revision was recorded. If it fails: validation_error points to the Rego line.
5. Activate. Set Status to Active and click Save as a new revision. Expected result: a new revision. If it fails: check your role.

Compare two revisions

1. Open the revisions. Open the policy, then Revisions. Expected result: the revision table. If it fails: No version yet means no revision.
2. Pick two rows. Click the older then the newer revision. Expected result: the line From revision a to revision b and the field diff. If it fails: a third click restarts the range.
3. Compare the decisions. Click Compare the decisions of the two revisions. Expected result: the counts and one row per input. If it fails: check that the request of Test request is valid JSON.

warning

An Active policy applies at once to every request of the tenant. Simulate it and keep it Draft until the simulation shows no unexpected Deny to allow change.

Troubleshooting

Symptom	Cause	Fix
Saving requires the tenant_admin or security_officer role.	Your roles cannot write policies.	Ask for the security_officer role.
Error validation_error (422)	Invalid Rego, invalid request or invalid inputs.	Fix the line or the field named in errors.
Error policy_engine_unavailable (503)	The OPA engine is not reachable.	Check the OPA service, then save again.
Error simulation_engine_unsupported (422)	The engine of the candidate cannot be simulated.	Change the engine or test with Evaluate with the active policies.
No input to compare.	The request is empty.	Fill Test request.

Related pages

• Policy development
• Policies (security)
• Policy simulator
• Decisions log