Policy Management

Policies are the rules that govern your AI agents. Each policy rule matches against specific conditions (operation, target integration, resource scope, data classification) and produces an effect: allow, approval_required, or deny. When an agent requests an action, the policy engine evaluates all matching rules and applies the highest-priority match.

Creating a policy rule

curl -X POST https://api.agentidentity.dev/api/v1/policies \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "policy_name": "Require approval for confidential data access",
    "operation": "database_query",
    "target_integration": "postgres",
    "resource_scope": "customers/*",
    "data_classification": "confidential",
    "policy_effect": "approval_required",
    "rationale": "All queries against confidential customer data must be reviewed by a human before execution to prevent data leaks.",
    "priority": 100,
    "conditions": null,
    "max_session_ttl": 3600,
    "modified_by": "[email protected]"
  }'

Policy rule fields

Effects

Priority and rule matching

When an agent requests an action, the policy engine:

1. Finds all active policy rules for the agent.
2. Filters rules where the operation, target_integration, resource_scope, and data_classification match the request. Wildcard (*) matches everything.
3. Selects the rule with the highest priority value.
4. If no rules match, the default behavior is deny (deny-by-default).

Use priority values to create layered policies:

Priority 200: deny   — block all restricted data operations
Priority 100: approval_required — require approval for confidential data
Priority  50: allow  — allow all internal data operations
Priority  10: allow  — allow read operations on public data

Versioning

Every update to a policy rule increments its policy_version and creates a version history entry. This provides a complete audit trail of policy changes.

View version history

curl "https://api.agentidentity.dev/api/v1/policies/{id}/versions?limit=10&offset=0" \
  -H "Authorization: Bearer $API_KEY"

Each version record includes the full policy state at that point in time, the modifier, and the timestamp.

Updating a policy rule

curl -X PATCH https://api.agentidentity.dev/api/v1/policies/{id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_effect": "deny",
    "rationale": "Updated: all access to customer data is now blocked pending security review."
  }'

All mutable fields can be updated individually. The policy_version is incremented automatically.

Deactivating a policy rule

Soft-delete (deactivate) a policy rule. Deactivated rules are no longer evaluated by the policy engine but remain in the system for audit purposes.

curl -X DELETE https://api.agentidentity.dev/api/v1/policies/{id} \
  -H "Authorization: Bearer $API_KEY"

Listing policy rules

curl "https://api.agentidentity.dev/api/v1/policies?agent_id={agent_id}&effect=approval_required&is_active=true" \
  -H "Authorization: Bearer $API_KEY"

Query parameters:

Dry-run testing

Test how the policy engine would evaluate a specific action without creating traces or approval requests. This is useful for validating your policy configuration.

curl -X POST https://api.agentidentity.dev/api/v1/policies/test \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "operation": "database_query",
    "target_integration": "postgres",
    "resource_scope": "customers/profiles",
    "data_classification": "confidential"
  }'

The response shows which rule matched, the effect, and the rationale -- without any side effects.

Dashboard

In the SidClaw dashboard, the Policies page provides:

• A filterable list of all policy rules with effect badges (green for allow, amber for approval_required, red for deny)
• Click-through to policy detail with version history
• Create and edit forms with validation
• Dry-run testing panel for ad hoc policy evaluation
• Active/inactive toggle for enabling or disabling rules
• Priority visualization showing rule precedence