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)	Full access
API Key (X-Api-Key: zhn_live_xxx)	Read-only (GET only)

---

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"]
  }
}

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"
  }
}