Contextual Security Policies (CSP)

CSPs are security and context policies consumed by agents during execution, dynamically injected into the prompt building process.

Policy Types

Type	Description
schedule	Time-based restrictions (allowed hours, days)
behavior	Agent behavior rules (tone, must_do, must_not)
data	Data access restrictions (sensitive fields, entities)
origin	Request origin restrictions (IPs, domains)
custom	Custom rules (flexible JSON)

Scopes

Policies are inherited from broader to narrower scope. More specific scopes override broader ones.

tenant → team → agent → user

Scope	Description
tenant	Applies to entire tenant
team	Applies to a specific team
agent	Applies to a specific agent
user	Applies to a specific user

Authentication

Method	Access
JWT (Authorization: Bearer <jwt> + x-tenant-id)	RBAC by tenant_users.role
API Key (X-Api-Key: YOUR_API_KEY)	RBAC by tenant_api_keys.role

RBAC Enforcement

Both JWT and API Key are subject to the same role-based permission check. The role determines which operations are allowed (e.g., editor can read and create but cannot delete CSPs). See API Keys - Role System for the full permission matrix.

---

GET /api/csp

List all CSPs for the tenant.

Query Parameters:

Param	Type	Description
scope	string	Filter by scope
policy_type	string	Filter by type
is_active	boolean	Filter active only
scope_target_id	UUID	Filter by target ID

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "Business Hours Only",
      "policy_type": "schedule",
      "scope": "tenant",
      "rules": {
        "allowed_hours": { "start": "08:00", "end": "18:00" }
      },
      "is_active": true,
      "priority": 10
    }
  ],
  "total": 5
}

---

GET /api/csp/effective

Get effective CSPs for a context, resolving the inheritance hierarchy.

Query Parameters:

Param	Type	Description
team_id	UUID	Team context
agent_id	UUID	Agent context
user_id	UUID	User context

Response:

{
  "data": [
    { "id": "uuid", "name": "Tenant Rules", "policy_type": "behavior", "scope": "tenant" },
    { "id": "uuid", "name": "Agent Rules", "policy_type": "data", "scope": "agent" }
  ],
  "resolution_chain": ["tenant", "agent"]
}

---

GET /api/csp/:id

Get CSP by ID.

POST /api/csp

Create a new CSP.

Request Body:

{
  "name": "Business Hours Only",
  "policy_type": "schedule",
  "scope": "tenant",
  "rules": {
    "allowed_hours": { "start": "08:00", "end": "18:00" },
    "allowed_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "timezone": "America/Sao_Paulo"
  },
  "is_active": true,
  "priority": 10
}

PUT /api/csp/:id

Update a CSP (partial update).

PATCH /api/csp/:id/toggle

Toggle CSP active status.

DELETE /api/csp/:id

Delete a CSP.

---

Policy Rule Examples

Schedule Policy

{
  "policy_type": "schedule",
  "rules": {
    "allowed_hours": { "start": "08:00", "end": "18:00" },
    "allowed_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "timezone": "America/Sao_Paulo"
  }
}

Behavior Policy

{
  "policy_type": "behavior",
  "rules": {
    "tone": "professional",
    "language": "pt-BR",
    "must_do": ["greet_user", "confirm_before_delete", "provide_sources"],
    "must_not": ["share_competitor_data", "execute_without_confirmation"],
    "max_iterations": 10,
    "must_not_tools": ["dangerous_tool"],
    "max_tokens_per_request": 4096
  }
}

Behavior Guardrails

The following behavior rules are enforced at runtime via the agent loop (not just injected into the prompt):

Field	Effect
max_iterations	Limits the number of agent loop iterations
must_not_tools	Blocks specific tools from being called by the agent
max_tokens_per_request	Limits max tokens per LLM request

These guardrails are extracted from the behavior policy in the policy-gate and propagated to the agent loop configuration.

Data Policy

{
  "policy_type": "data",
  "rules": {
    "sensitive_fields": ["cpf", "cnpj", "password"],
    "mask_pattern": "[REDACTED]",
    "never_expose": ["api_key", "secret_token"],
    "restricted_entities": ["Competitor Inc"],
    "restriction_message": "You don't have access to this data."
  }
}

Origin Policy

{
  "policy_type": "origin",
  "rules": {
    "allowed_origins": ["https://app.zihin.ai", "https://*.zihin.ai"],
    "blocked_origins": ["http://*"],
    "allowed_ips": ["192.168.1.0/24"],
    "reason": "Only HTTPS origins allowed"
  }
}