Create Policy

Create governance policies that define how agent actions and MCP server operations are evaluated, approved, or denied.

Endpoint

POST /api/mcp/policies

Authentication

JWT Token required - Authorization: Bearer <token> header

Requires admin or security_manager role.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token with admin/security role
Content-Type	Yes	Must be application/json

Body

{
  "policy_name": "Block Production Database Writes",
  "policy_description": "Block all write operations to production databases during business hours",
  "server_patterns": ["*-production-*", "prod-*"],
  "namespace_patterns": ["database"],
  "verb_patterns": ["write_*", "delete_*", "update_*", "insert_*"],
  "resource_patterns": ["production-db/*", "prod-*"],
  "risk_threshold": 50,
  "action": "DENY",
  "required_approval_level": 3,
  "compliance_framework": "SOC2"
}

Parameters

Parameter	Type	Required	Description
policy_name	string	Yes	Unique policy name
policy_description	string	No	Human-readable description
server_patterns	array	No	MCP server ID patterns to match (supports wildcards)
namespace_patterns	array	No	MCP namespace patterns to match
verb_patterns	array	No	Action verb patterns to match
resource_patterns	array	No	Resource path patterns to match
risk_threshold	integer	No	Risk score threshold (0-100, default: 50)
action	string	No	Policy action: ALLOW, DENY, EVALUATE (default: EVALUATE)
required_approval_level	integer	No	Approval level required (1-5, default: 1)
compliance_framework	string	No	Compliance framework tag (e.g., SOC2, HIPAA, PCI-DSS)

Policy Actions

Action	Description
ALLOW	Automatically approve matching actions
DENY	Automatically deny matching actions
EVALUATE	Evaluate against risk threshold; require approval if exceeded

Pattern Matching

Patterns support wildcard matching:

• * - Matches any sequence of characters
• ? - Matches any single character

Examples:

• prod-* matches prod-db-01, prod-api-server
• write_* matches write_file, write_record
• */secrets/* matches config/secrets/api-key

Response

Success (201 Created)

{
  "policy_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "policy_name": "Block Production Database Writes",
  "status": "created",
  "is_active": true
}

Response Fields

Field	Type	Description
policy_id	string	Unique policy identifier (UUID)
policy_name	string	Policy name
status	string	Creation status
is_active	boolean	Whether policy is active

Errors

Code	Description
400	Bad request - validation error
401	Unauthorized - missing or invalid JWT token
403	Forbidden - insufficient permissions
409	Conflict - policy name already exists
500	Internal server error

Validation Error (400):

{
  "detail": "policy_name is required",
  "error_code": "VALIDATION_ERROR",
  "status": 400
}

Policy Examples

1. Block All Production Writes

{
  "policy_name": "Block Production Writes",
  "policy_description": "Deny all write operations to production systems",
  "resource_patterns": ["production/*", "prod-*"],
  "verb_patterns": ["write_*", "delete_*", "drop_*"],
  "action": "DENY",
  "compliance_framework": "SOC2"
}

2. Require Approval for PII Access

{
  "policy_name": "PII Access Approval",
  "policy_description": "Require manager approval for any PII data access",
  "namespace_patterns": ["customer_data", "user_profiles", "pii_*"],
  "action": "EVALUATE",
  "risk_threshold": 40,
  "required_approval_level": 2,
  "compliance_framework": "GDPR"
}

3. Auto-Approve Read-Only Operations

{
  "policy_name": "Auto-Approve Read Operations",
  "policy_description": "Automatically approve read-only operations",
  "verb_patterns": ["read_*", "get_*", "list_*", "describe_*"],
  "action": "ALLOW",
  "risk_threshold": 30
}

4. Block After Hours Operations

{
  "policy_name": "Business Hours Only",
  "policy_description": "Block high-risk operations outside business hours",
  "risk_threshold": 70,
  "action": "DENY",
  "compliance_framework": "SOC2"
}

5. Healthcare Data Protection

{
  "policy_name": "HIPAA PHI Protection",
  "policy_description": "Require executive approval for protected health information access",
  "namespace_patterns": ["healthcare/*", "phi/*", "medical_records"],
  "resource_patterns": ["patient_*", "*_health_*"],
  "action": "EVALUATE",
  "risk_threshold": 60,
  "required_approval_level": 4,
  "compliance_framework": "HIPAA"
}

Examples

cURL

curl -X POST https://pilot.owkai.app/api/mcp/policies \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiI..." \
  -H "Content-Type: application/json" \
  -d '{
    "policy_name": "Block Production Database Writes",
    "policy_description": "Block all write operations to production databases",
    "resource_patterns": ["production-db/*", "prod-*"],
    "verb_patterns": ["write_*", "delete_*", "update_*"],
    "action": "DENY",
    "compliance_framework": "SOC2"
  }'

Python

from ascend import AscendClient

client = AscendClient(access_token="eyJhbGciOiJSUzI1NiI...")

# Create a deny policy for production writes
policy = client.policies.create(
    policy_name="Block Production Database Writes",
    policy_description="Block all write operations to production databases",
    resource_patterns=["production-db/*", "prod-*"],
    verb_patterns=["write_*", "delete_*", "update_*"],
    action="DENY",
    compliance_framework="SOC2"
)

print(f"Policy created: {policy.policy_id}")
print(f"Active: {policy.is_active}")

Node.js

import { AscendClient } from '@ascend-ai/sdk';

const client = new AscendClient({ accessToken: 'eyJhbGciOiJSUzI1NiI...' });

const policy = await client.policies.create({
  policyName: 'Block Production Database Writes',
  policyDescription: 'Block all write operations to production databases',
  resourcePatterns: ['production-db/*', 'prod-*'],
  verbPatterns: ['write_*', 'delete_*', 'update_*'],
  action: 'DENY',
  complianceFramework: 'SOC2'
});

console.log(`Policy created: ${policy.policyId}`);

Python (requests)

import requests

response = requests.post(
    "https://pilot.owkai.app/api/mcp/policies",
    headers={
        "Authorization": "Bearer eyJhbGciOiJSUzI1NiI...",
        "Content-Type": "application/json"
    },
    json={
        "policy_name": "Block Production Database Writes",
        "policy_description": "Block all write operations to production databases",
        "resource_patterns": ["production-db/*", "prod-*"],
        "verb_patterns": ["write_*", "delete_*", "update_*"],
        "action": "DENY",
        "compliance_framework": "SOC2"
    }
)

result = response.json()
print(f"Policy ID: {result['policy_id']}")

Agent-Level Policies

You can also create policies specific to individual agents:

POST /api/registry/agents/{agent_id}/policies

Request Body:

{
  "policy_name": "Agent-Specific PII Block",
  "policy_description": "Block this agent from accessing PII data",
  "policy_action": "block",
  "conditions": {
    "resource_contains": "pii",
    "data_classification": ["confidential", "restricted"]
  },
  "priority": 100,
  "is_active": true
}

This creates a policy that applies only to the specified agent.

Policy Evaluation Order

Policies are evaluated in the following order:

1. Agent-specific policies (highest priority)
2. Organization policies (by priority field, descending)
3. System default policies (lowest priority)

Within each level, policies are evaluated by priority field (higher numbers = higher priority).

Compliance Frameworks

Common compliance framework values:

Framework	Description
SOC2	SOC 2 Type II compliance
HIPAA	Healthcare data protection
PCI-DSS	Payment card industry
GDPR	EU data protection
SOX	Sarbanes-Oxley Act
NIST	NIST 800-53 controls
ISO27001	Information security management

Related Endpoints

• List Policies - List all policies