Policies Service

The Policies Service gives you programmatic control over security, access, and governance policies in the Kubiya platform. Policies define what actions agents, users, or teams can perform on resources, enabling you to enforce fine-grained authorization, compliance, and operational best practices. By managing policies, you can ensure that only the right entities have access to sensitive operations, automate approvals, and maintain a secure environment as your organization grows.

For conceptual information about policies and how they’re used in the platform, see Policies Core Concepts.

Overview

The Policies Service enables you to:

List policies with pagination support
Get policy details including rules, conditions, and enforcement settings
Create custom policies for access control and governance
Update policy configurations for existing policies
Delete policies when no longer needed
Evaluate policies for specific entities and actions
Check authorization before performing actions

Quick Start

from kubiya import ControlPlaneClient

# Initialize client
client = ControlPlaneClient(api_key="your-api-key")

# List all policies
policies = client.policies.list()
for policy in policies:
    print(f"Policy: {policy['name']} - Type: {policy.get('type', 'N/A')}")

# Check if an agent is authorized
authorization = client.policies.check_authorization(
    entity_id="agent-uuid",
    resource="production-database",
    action="read"
)
print(f"Authorized: {authorization['allowed']}")

List Policies

List all policies with pagination support.

The Policies Service uses page-based pagination (page 1, 2, 3…) instead of skip/limit pagination used by other services.

Basic Listing

# List first page of policies (default: 100 per page)
policies = client.policies.list()

for policy in policies:
    print(f"""
    Name: {policy['name']}
    Type: {policy.get('type', 'N/A')}
    Enabled: {policy.get('enabled', True)}
    Priority: {policy.get('priority', 0)}
    """)

Paginated Listing

# List policies with page-based pagination
page = 1
limit = 20

while True:
    policies = client.policies.list(page=page, limit=limit)

    if not policies:
        break

    for policy in policies:
        print(f"Policy: {policy['name']}")

    page += 1

List All Policies

def list_all_policies():
    """Get all policies across all pages"""
    all_policies = []
    page = 1
    limit = 100

    while True:
        policies = client.policies.list(page=page, limit=limit)

        if not policies:
            break

        all_policies.extend(policies)
        page += 1

    return all_policies

# Usage
all_policies = list_all_policies()
print(f"Total policies: {len(all_policies)}")

Filter Policies by Type

def filter_policies_by_type(policy_type: str):
    """Filter policies by type"""
    all_policies = client.policies.list(page=1, limit=1000)

    return [p for p in all_policies if p.get('type') == policy_type]

# Usage
rbac_policies = filter_policies_by_type("rbac")
print(f"RBAC policies: {len(rbac_policies)}")

approval_policies = filter_policies_by_type("approval")
print(f"Approval policies: {len(approval_policies)}")

Get Policy Details

Retrieve detailed information about a specific policy.

By Policy ID

# Get policy by UUID
policy = client.policies.get("policy-uuid-here")

print(f"Policy: {policy['name']}")
print(f"Description: {policy.get('description', 'N/A')}")
print(f"Type: {policy.get('type', 'N/A')}")
print(f"Rules: {policy.get('rules', [])}")
print(f"Conditions: {policy.get('conditions', {})}")
print(f"Enforcement: {policy.get('enforcement', 'enforce')}")

Extract Policy Information

def get_policy_info(policy_id: str):
    """Get comprehensive policy information"""
    try:
        policy = client.policies.get(policy_id)

        info = {
            "id": policy.get('uuid'),
            "name": policy['name'],
            "description": policy.get('description'),
            "type": policy.get('type'),
            "enabled": policy.get('enabled', True),
            "priority": policy.get('priority', 0),
            "rules": policy.get('rules', []),
            "conditions": policy.get('conditions', {}),
            "enforcement": policy.get('enforcement', 'enforce'),
            "scope": policy.get('scope', 'global')
        }

        return info
    except Exception as e:
        print(f"Failed to get policy info: {e}")
        return None

# Usage
info = get_policy_info("policy-uuid")
if info:
    print(f"Policy: {info['name']}")
    print(f"Enforcement: {info['enforcement']}")
    print(f"Rules: {len(info['rules'])}")

Find Policy by Name

def find_policy_by_name(name: str):
    """Find a policy by name"""
    page = 1

    while True:
        policies = client.policies.list(page=page, limit=100)

        if not policies:
            break

        for policy in policies:
            if policy['name'].lower() == name.lower():
                return policy

        page += 1

    return None

# Usage
prod_policy = find_policy_by_name("production-access-control")
if prod_policy:
    print(f"Found policy: {prod_policy['uuid']}")
    policy_details = client.policies.get(prod_policy['uuid'])
    print(f"Rules: {policy_details.get('rules', [])}")

Create Policy

Create a new security or access control policy.

Basic RBAC Policy

# Create a basic RBAC policy
policy_data = {
    "name": "developer-read-only",
    "description": "Developers can read resources but not modify them",
    "type": "rbac",
    "rules": [
        {
            "effect": "allow",
            "actions": ["read", "list", "get"],
            "resources": ["*"],
            "principals": ["role:developer"]
        },
        {
            "effect": "deny",
            "actions": ["write", "update", "delete"],
            "resources": ["*"],
            "principals": ["role:developer"]
        }
    ],
    "enabled": True,
    "priority": 100
}

created_policy = client.policies.create(policy_data)
print(f"Created policy: {created_policy['uuid']}")
print(f"Name: {created_policy['name']}")

Resource-Specific Policy

# Create a policy for specific resources
policy_data = {
    "name": "production-database-access",
    "description": "Control access to production databases",
    "type": "rbac",
    "rules": [
        {
            "effect": "allow",
            "actions": ["read", "query"],
            "resources": ["database:production:*"],
            "principals": ["role:database-admin", "role:senior-developer"]
        },
        {
            "effect": "deny",
            "actions": ["delete", "truncate", "drop"],
            "resources": ["database:production:*"],
            "principals": ["*"]
        }
    ],
    "conditions": {
        "time_range": {
            "start": "09:00",
            "end": "17:00"
        },
        "ip_allowlist": ["10.0.0.0/8"]
    },
    "enabled": True,
    "priority": 200
}

created_policy = client.policies.create(policy_data)
print(f"Created resource-specific policy: {created_policy['uuid']}")

Approval Workflow Policy

# Create an approval policy
policy_data = {
    "name": "production-deployment-approval",
    "description": "Require approval for production deployments",
    "type": "approval",
    "rules": [
        {
            "effect": "require_approval",
            "actions": ["deploy", "release"],
            "resources": ["environment:production"],
            "principals": ["*"],
            "approval_config": {
                "required_approvers": 2,
                "approver_roles": ["deployment-manager", "engineering-lead"],
                "timeout_hours": 24
            }
        }
    ],
    "enabled": True,
    "priority": 300
}

created_policy = client.policies.create(policy_data)
print(f"Created approval policy: {created_policy['uuid']}")

Time-Based Policy

# Create a time-based access policy
policy_data = {
    "name": "after-hours-restrictions",
    "description": "Restrict certain actions outside business hours",
    "type": "rbac",
    "rules": [
        {
            "effect": "deny",
            "actions": ["deploy", "modify", "delete"],
            "resources": ["environment:production"],
            "principals": ["*"],
            "conditions": {
                "time_window": {
                    "outside": {
                        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
                        "hours": {"start": "06:00", "end": "22:00"}
                    }
                }
            }
        }
    ],
    "enabled": True,
    "priority": 150
}

created_policy = client.policies.create(policy_data)
print(f"Created time-based policy: {created_policy['uuid']}")

Update Policy

Update an existing policy configuration.

Basic Update

# Update policy settings
policy_id = "policy-uuid-here"

update_data = {
    "description": "Updated policy description",
    "enabled": True,
    "priority": 200
}

updated_policy = client.policies.update(policy_id, update_data)
print(f"Updated policy: {updated_policy['name']}")

Add Rules to Policy

def add_rules_to_policy(policy_id: str, new_rules: list):
    """Add rules to an existing policy"""
    # Get current policy
    policy = client.policies.get(policy_id)

    # Get current rules
    current_rules = policy.get('rules', [])

    # Add new rules
    updated_rules = current_rules + new_rules

    # Update policy
    update_data = {"rules": updated_rules}
    updated_policy = client.policies.update(policy_id, update_data)

    return updated_policy

# Usage
new_rules = [
    {
        "effect": "allow",
        "actions": ["backup"],
        "resources": ["database:*"],
        "principals": ["role:backup-operator"]
    }
]

updated = add_rules_to_policy("policy-uuid", new_rules)
print(f"Updated policy with {len(updated['rules'])} rules")

Enable/Disable Policy

def toggle_policy(policy_id: str, enabled: bool):
    """Enable or disable a policy"""
    update_data = {"enabled": enabled}
    updated_policy = client.policies.update(policy_id, update_data)

    status = "enabled" if enabled else "disabled"
    print(f"Policy {policy_id} is now {status}")

    return updated_policy

# Usage
toggle_policy("policy-uuid", False)  # Disable
toggle_policy("policy-uuid", True)   # Enable

Update Policy Priority

def update_policy_priority(policy_id: str, priority: int):
    """Update policy priority (higher priority evaluated first)"""
    update_data = {"priority": priority}
    updated_policy = client.policies.update(policy_id, update_data)

    print(f"Updated policy priority to {priority}")
    return updated_policy

# Usage
update_policy_priority("policy-uuid", 500)

Delete Policy

Delete a policy.

Deleting a policy affects authorization checks for all entities. Ensure the policy is no longer needed before deletion.

# Delete policy
policy_id = "policy-uuid-to-delete"

result = client.policies.delete(policy_id)
print(f"Deletion result: {result}")

Delete with Safety Check

from kubiya.resources.exceptions import PolicyError

def delete_policy_safe(policy_id: str):
    """Delete policy with confirmation"""
    try:
        # Get policy details first
        policy = client.policies.get(policy_id)

        print(f"About to delete policy: {policy['name']}")
        print(f"Type: {policy.get('type')}")
        print(f"Enabled: {policy.get('enabled')}")

        # Perform deletion
        result = client.policies.delete(policy_id)

        return {
            "success": True,
            "message": f"Deleted policy: {policy['name']}",
            "result": result
        }
    except PolicyError as e:
        return {
            "success": False,
            "message": str(e)
        }

# Usage
result = delete_policy_safe("policy-uuid")
if result['success']:
    print(f"✅ {result['message']}")
else:
    print(f"❌ Deletion failed: {result['message']}")

Evaluate Policy

Evaluate a policy for a specific entity and action.

Basic Evaluation

# Evaluate if an entity can perform an action
evaluation = client.policies.evaluate(
    entity_id="agent-uuid",
    action="deploy"
)

if evaluation.get('allowed'):
    print("✅ Action is allowed")
else:
    print(f"❌ Action is denied: {evaluation.get('reason')}")

Evaluate with Resource Context

# Evaluate with resource information
evaluation = client.policies.evaluate(
    entity_id="user-uuid",
    action="delete",
    resource={
        "type": "database",
        "environment": "production",
        "name": "customer-data"
    }
)

if evaluation.get('allowed'):
    print("✅ Action is allowed")
    print(f"Applicable policies: {evaluation.get('applied_policies', [])}")
else:
    print(f"❌ Action is denied")
    print(f"Reason: {evaluation.get('reason')}")
    print(f"Denied by: {evaluation.get('denied_by')}")

Evaluate Multiple Actions

def evaluate_multiple_actions(entity_id: str, actions: list, resource=None):
    """Evaluate multiple actions for an entity"""
    results = {}

    for action in actions:
        try:
            evaluation = client.policies.evaluate(
                entity_id=entity_id,
                action=action,
                resource=resource
            )
            results[action] = {
                "allowed": evaluation.get('allowed', False),
                "reason": evaluation.get('reason'),
                "applied_policies": evaluation.get('applied_policies', [])
            }
        except PolicyError as e:
            results[action] = {
                "allowed": False,
                "reason": str(e),
                "error": True
            }

    return results

# Usage
actions = ["read", "write", "delete", "deploy"]
results = evaluate_multiple_actions("agent-uuid", actions)

print("Action Evaluation Results:")
for action, result in results.items():
    status = "✅ ALLOWED" if result['allowed'] else "❌ DENIED"
    print(f"  {action}: {status}")
    if not result['allowed']:
        print(f"    Reason: {result.get('reason')}")

Check Authorization

Check if an entity is authorized for a specific action on a resource.

Basic Authorization Check

# Check if entity is authorized
authorization = client.policies.check_authorization(
    entity_id="agent-uuid",
    resource="database:production:customers",
    action="read"
)

if authorization.get('allowed'):
    print("✅ Authorized")
else:
    print(f"❌ Not authorized: {authorization.get('reason')}")

Pre-Action Authorization

def require_authorization(entity_id: str, resource: str, action: str):
    """Decorator-style authorization check"""
    authorization = client.policies.check_authorization(
        entity_id=entity_id,
        resource=resource,
        action=action
    )

    if not authorization.get('allowed'):
        raise PermissionError(f"Not authorized: {authorization.get('reason')}")

    return authorization

# Usage
try:
    require_authorization("agent-uuid", "production-database", "delete")
    print("Proceeding with delete operation...")
    # ... perform delete ...
except PermissionError as e:
    print(f"Authorization denied: {e}")

Bulk Authorization Check

def check_authorization_bulk(entity_id: str, checks: list):
    """Check authorization for multiple resource/action pairs"""
    results = {}

    for check in checks:
        resource = check['resource']
        action = check['action']

        try:
            authorization = client.policies.check_authorization(
                entity_id=entity_id,
                resource=resource,
                action=action
            )
            results[f"{resource}:{action}"] = {
                "allowed": authorization.get('allowed', False),
                "reason": authorization.get('reason'),
                "policies": authorization.get('applied_policies', [])
            }
        except PolicyError as e:
            results[f"{resource}:{action}"] = {
                "allowed": False,
                "reason": str(e),
                "error": True
            }

    return results

# Usage
checks = [
    {"resource": "database:prod:customers", "action": "read"},
    {"resource": "database:prod:customers", "action": "write"},
    {"resource": "environment:production", "action": "deploy"}
]

results = check_authorization_bulk("agent-uuid", checks)

print("Authorization Check Results:")
for check, result in results.items():
    status = "✅ ALLOWED" if result['allowed'] else "❌ DENIED"
    print(f"  {check}: {status}")

Practical Examples

1. Policy Audit System

def audit_policies():
    """Generate comprehensive policy audit report"""
    page = 1
    all_policies = []

    # Collect all policies
    while True:
        policies = client.policies.list(page=page, limit=100)
        if not policies:
            break
        all_policies.extend(policies)
        page += 1

    audit = {
        "total_policies": len(all_policies),
        "enabled": 0,
        "disabled": 0,
        "by_type": {},
        "by_priority": {},
        "high_priority": [],  # priority >= 200
        "policies_without_description": []
    }

    for policy in all_policies:
        # Count enabled/disabled
        if policy.get('enabled', True):
            audit['enabled'] += 1
        else:
            audit['disabled'] += 1

        # Count by type
        policy_type = policy.get('type', 'unknown')
        audit['by_type'][policy_type] = audit['by_type'].get(policy_type, 0) + 1

        # Track high priority policies
        priority = policy.get('priority', 0)
        if priority >= 200:
            audit['high_priority'].append({
                "name": policy['name'],
                "priority": priority,
                "type": policy_type
            })

        # Track policies without description
        if not policy.get('description'):
            audit['policies_without_description'].append(policy['name'])

    return audit

# Usage
audit = audit_policies()
print(f"Policy Audit Report:")
print(f"  Total Policies: {audit['total_policies']}")
print(f"  Enabled: {audit['enabled']}")
print(f"  Disabled: {audit['disabled']}")
print(f"\nBy Type:")
for policy_type, count in audit['by_type'].items():
    print(f"  {policy_type}: {count}")
print(f"\nHigh Priority Policies: {len(audit['high_priority'])}")

2. Policy Compliance Checker

def check_policy_compliance(required_policies: list):
    """Check if required policies are in place"""
    page = 1
    all_policies = []

    while True:
        policies = client.policies.list(page=page, limit=100)
        if not policies:
            break
        all_policies.extend(policies)
        page += 1

    policy_names = {p['name']: p for p in all_policies}

    compliance_report = {
        "compliant": True,
        "missing_policies": [],
        "disabled_policies": [],
        "compliance_score": 0
    }

    for required in required_policies:
        if required not in policy_names:
            compliance_report['missing_policies'].append(required)
            compliance_report['compliant'] = False
        elif not policy_names[required].get('enabled', True):
            compliance_report['disabled_policies'].append(required)
            compliance_report['compliant'] = False

    # Calculate compliance score
    found = len(required_policies) - len(compliance_report['missing_policies'])
    enabled = found - len(compliance_report['disabled_policies'])
    compliance_report['compliance_score'] = (enabled / len(required_policies)) * 100 if required_policies else 100

    return compliance_report

# Usage
required_policies = [
    "production-access-control",
    "deployment-approval",
    "data-protection",
    "audit-logging"
]

compliance = check_policy_compliance(required_policies)
print(f"Compliance Score: {compliance['compliance_score']:.1f}%")
if compliance['missing_policies']:
    print(f"❌ Missing: {compliance['missing_policies']}")
if compliance['disabled_policies']:
    print(f"⚠️  Disabled: {compliance['disabled_policies']}")

3. Permission Matrix Generator

def generate_permission_matrix(entity_ids: list, resources: list, actions: list):
    """Generate a permission matrix for entities"""
    matrix = {}

    for entity_id in entity_ids:
        matrix[entity_id] = {}

        for resource in resources:
            matrix[entity_id][resource] = {}

            for action in actions:
                try:
                    auth = client.policies.check_authorization(
                        entity_id=entity_id,
                        resource=resource,
                        action=action
                    )
                    matrix[entity_id][resource][action] = auth.get('allowed', False)
                except PolicyError:
                    matrix[entity_id][resource][action] = False

    return matrix

# Usage
entities = ["agent-1", "agent-2", "user-1"]
resources = ["database:prod", "environment:staging", "secrets:api-keys"]
actions = ["read", "write", "delete"]

matrix = generate_permission_matrix(entities, resources, actions)

# Display matrix
print(f"{'Entity':<20} {'Resource':<30} {'Read':<8} {'Write':<8} {'Delete':<8}")
print("-" * 80)
for entity_id, resources in matrix.items():
    for resource, actions in resources.items():
        read = "✅" if actions.get('read') else "❌"
        write = "✅" if actions.get('write') else "❌"
        delete = "✅" if actions.get('delete') else "❌"
        print(f"{entity_id:<20} {resource:<30} {read:<8} {write:<8} {delete:<8}")

4. Policy Template Library

class PolicyTemplates:
    """Common policy templates"""

    @staticmethod
    def create_rbac_policy(role: str, allowed_actions: list, resources: list):
        """Create a basic RBAC policy"""
        return {
            "name": f"rbac-{role}",
            "description": f"RBAC policy for {role} role",
            "type": "rbac",
            "rules": [
                {
                    "effect": "allow",
                    "actions": allowed_actions,
                    "resources": resources,
                    "principals": [f"role:{role}"]
                }
            ],
            "enabled": True,
            "priority": 100
        }

    @staticmethod
    def create_time_restricted_policy(name: str, restricted_actions: list, time_window: dict):
        """Create a time-restricted policy"""
        return {
            "name": name,
            "description": f"Time-restricted policy: {name}",
            "type": "rbac",
            "rules": [
                {
                    "effect": "deny",
                    "actions": restricted_actions,
                    "resources": ["*"],
                    "principals": ["*"],
                    "conditions": {"time_window": time_window}
                }
            ],
            "enabled": True,
            "priority": 150
        }

    @staticmethod
    def create_approval_policy(resource_pattern: str, approver_roles: list, required_count: int):
        """Create an approval workflow policy"""
        return {
            "name": f"approval-{resource_pattern.replace(':', '-')}",
            "description": f"Approval required for {resource_pattern}",
            "type": "approval",
            "rules": [
                {
                    "effect": "require_approval",
                    "actions": ["*"],
                    "resources": [resource_pattern],
                    "principals": ["*"],
                    "approval_config": {
                        "required_approvers": required_count,
                        "approver_roles": approver_roles,
                        "timeout_hours": 24
                    }
                }
            ],
            "enabled": True,
            "priority": 200
        }

# Usage
templates = PolicyTemplates()

# Create RBAC policy
rbac_policy = templates.create_rbac_policy(
    role="developer",
    allowed_actions=["read", "list"],
    resources=["database:*", "environment:dev"]
)
created = client.policies.create(rbac_policy)
print(f"Created RBAC policy: {created['uuid']}")

# Create time-restricted policy
time_policy = templates.create_time_restricted_policy(
    name="after-hours-deployment-block",
    restricted_actions=["deploy", "release"],
    time_window={
        "outside": {
            "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
            "hours": {"start": "09:00", "end": "17:00"}
        }
    }
)
created = client.policies.create(time_policy)
print(f"Created time-restricted policy: {created['uuid']}")

Error Handling

When working with policies, you may encounter errors such as requesting a non-existent policy, failing evaluation, or authorization checks. These examples show how to handle such errors gracefully and provide fallback options to keep your workflows secure and robust.

from kubiya.resources.exceptions import PolicyError

try:
    # Try to get a policy
    policy = client.policies.get("non-existent-policy")
except PolicyError as e:
    print(f"Policy error: {e}")
    # Handle error - maybe list all policies
    print("Available policies:")
    policies = client.policies.list(page=1, limit=10)
    for policy in policies:
        print(f"  - {policy['name']}")

# Evaluate with error handling
try:
    evaluation = client.policies.evaluate(
        entity_id="agent-uuid",
        action="deploy"
    )
    if evaluation.get('allowed'):
        print("Action is allowed")
    else:
        print(f"Action denied: {evaluation.get('reason')}")
except PolicyError as e:
    print(f"Evaluation error: {e}")

# Authorization check with error handling
try:
    auth = client.policies.check_authorization(
        entity_id="user-uuid",
        resource="production-database",
        action="delete"
    )
    if not auth.get('allowed'):
        print(f"Not authorized: {auth.get('reason')}")
except PolicyError as e:
    print(f"Authorization check failed: {e}")

Best Practices

1. Use Priority for Policy Ordering

# Higher priority policies are evaluated first
# Critical security policies should have highest priority
security_policy = {
    "name": "critical-security",
    "priority": 1000,  # Evaluated first
    "rules": [...]
}

# General policies can have lower priority
general_policy = {
    "name": "general-access",
    "priority": 100,
    "rules": [...]
}

2. Always Check Authorization Before Actions

def perform_sensitive_action(entity_id: str, resource: str, action: str):
    """Always check authorization before sensitive operations"""
    # Check authorization first
    auth = client.policies.check_authorization(
        entity_id=entity_id,
        resource=resource,
        action=action
    )

    if not auth.get('allowed'):
        raise PermissionError(f"Not authorized: {auth.get('reason')}")

    # Proceed with action
    print(f"Performing {action} on {resource}...")
    # ... perform action ...

    return {"success": True}

# Usage
try:
    result = perform_sensitive_action("agent-uuid", "prod-db", "delete")
except PermissionError as e:
    print(f"❌ {e}")

3. Use Descriptive Policy Names

# Good - descriptive names
policy_data = {
    "name": "production-database-read-only-developers",
    "description": "Allows developers read-only access to production databases",
    "type": "rbac"
}

# Bad - vague names
policy_data = {
    "name": "policy-1",
    "description": "Some policy",
    "type": "rbac"
}

4. Test Policies Before Enabling

def test_policy_before_enabling(policy_data: dict, test_cases: list):
    """Test policy with sample cases before enabling"""
    # Create policy as disabled
    policy_data['enabled'] = False
    policy = client.policies.create(policy_data)

    print(f"Created test policy: {policy['uuid']}")

    # Run test cases
    all_passed = True
    for test_case in test_cases:
        auth = client.policies.check_authorization(
            entity_id=test_case['entity_id'],
            resource=test_case['resource'],
            action=test_case['action']
        )

        expected = test_case['expected_allowed']
        actual = auth.get('allowed', False)

        if expected != actual:
            print(f"❌ Test failed: {test_case}")
            all_passed = False
        else:
            print(f"✅ Test passed: {test_case}")

    # Enable if all tests passed
    if all_passed:
        client.policies.update(policy['uuid'], {"enabled": True})
        print("✅ All tests passed, policy enabled")
    else:
        print("❌ Tests failed, policy remains disabled")

    return all_passed

# Usage
test_cases = [
    {"entity_id": "dev-1", "resource": "prod-db", "action": "read", "expected_allowed": True},
    {"entity_id": "dev-1", "resource": "prod-db", "action": "delete", "expected_allowed": False}
]

test_policy_before_enabling(policy_data, test_cases)

API Reference

Methods

Method	Description	Parameters
`list(page, limit)`	List all policies	`page`: Page number (1, 2, 3…), `limit`: Records per page
`get(policy_id)`	Get specific policy	`policy_id`: Policy UUID
`create(policy_data)`	Create policy	`policy_data`: Policy configuration dictionary
`update(policy_id, policy_data)`	Update policy	`policy_id`: UUID, `policy_data`: Updates
`delete(policy_id)`	Delete policy	`policy_id`: Policy UUID
`evaluate(entity_id, action, resource)`	Evaluate policy	`entity_id`: Entity UUID, `action`: Action string, `resource`: Optional resource dict
`check_authorization(entity_id, resource, action)`	Check authorization	`entity_id`: Entity UUID, `resource`: Resource string, `action`: Action string

Policy Object Structure

{
    "uuid": "string",                    # Unique identifier
    "name": "string",                    # Policy name
    "description": "string",             # Policy description
    "type": "string",                    # Policy type (rbac, approval, etc.)
    "enabled": bool,                     # Whether policy is enabled
    "priority": int,                     # Policy priority (higher = evaluated first)
    "rules": [                           # List of policy rules
        {
            "effect": "string",          # allow, deny, require_approval
            "actions": ["string"],       # Actions (read, write, delete, etc.)
            "resources": ["string"],     # Resources (database:*, environment:prod, etc.)
            "principals": ["string"],    # Principals (role:admin, user:*, etc.)
            "conditions": dict           # Optional conditions
        }
    ],
    "conditions": dict,                  # Global policy conditions
    "enforcement": "string",             # enforce, audit, disabled
    "scope": "string",                   # Policy scope (global, org, team)
    "created_at": "string",              # Creation timestamp
    "updated_at": "string"               # Last update timestamp
}

Evaluation Result Object Structure

{
    "allowed": bool,                     # Whether action is allowed
    "reason": "string",                  # Reason for decision
    "applied_policies": ["string"],      # List of policy IDs that were applied
    "denied_by": "string"                # Policy that denied (if denied)
}

Authorization Result Object Structure

{
    "allowed": bool,                     # Whether entity is authorized
    "reason": "string",                  # Reason for decision
    "applied_policies": ["string"],      # Policies used in decision
    "entity_id": "string",               # Entity that was checked
    "resource": "string",                # Resource that was checked
    "action": "string"                   # Action that was checked
}

Next Steps

Agents Service

Create and manage agents

Skills Service

Manage skills and capabilities

Best Practices

SDK best practices guide

Getting Started

Control Plane API

Control Plane Client

Context Graph & Memory

Client SDK

Workflow DSL

Advanced

Resources

​Overview

​Quick Start

​List Policies

​Basic Listing

​Paginated Listing

​List All Policies

​Filter Policies by Type

​Get Policy Details

​By Policy ID

​Extract Policy Information

​Find Policy by Name

​Create Policy

​Basic RBAC Policy

​Resource-Specific Policy

​Approval Workflow Policy

​Time-Based Policy

​Update Policy

​Basic Update

​Add Rules to Policy

​Enable/Disable Policy

​Update Policy Priority

​Delete Policy

​Delete with Safety Check

​Evaluate Policy

​Basic Evaluation

​Evaluate with Resource Context

​Evaluate Multiple Actions

​Check Authorization

​Basic Authorization Check

​Pre-Action Authorization

​Bulk Authorization Check

​Practical Examples

​1. Policy Audit System

​2. Policy Compliance Checker

​3. Permission Matrix Generator

​4. Policy Template Library

​Error Handling

​Best Practices

​1. Use Priority for Policy Ordering

​2. Always Check Authorization Before Actions

​3. Use Descriptive Policy Names

​4. Test Policies Before Enabling

​API Reference

​Methods

​Policy Object Structure

​Evaluation Result Object Structure

​Authorization Result Object Structure

​Next Steps

Agents Service

Skills Service

Best Practices

Overview

Quick Start

List Policies

Basic Listing

Paginated Listing

List All Policies

Filter Policies by Type

Get Policy Details

By Policy ID

Extract Policy Information

Find Policy by Name

Create Policy

Basic RBAC Policy

Resource-Specific Policy

Approval Workflow Policy

Time-Based Policy

Update Policy

Basic Update

Add Rules to Policy

Enable/Disable Policy

Update Policy Priority

Delete Policy

Delete with Safety Check

Evaluate Policy

Basic Evaluation

Evaluate with Resource Context

Evaluate Multiple Actions

Check Authorization

Basic Authorization Check

Pre-Action Authorization

Bulk Authorization Check

Practical Examples

1. Policy Audit System

2. Policy Compliance Checker

3. Permission Matrix Generator

4. Policy Template Library

Error Handling

Best Practices

1. Use Priority for Policy Ordering

2. Always Check Authorization Before Actions

3. Use Descriptive Policy Names

4. Test Policies Before Enabling

API Reference

Methods

Policy Object Structure

Evaluation Result Object Structure

Authorization Result Object Structure

Next Steps