Access Policies

Policies control who can read, write, or delete memories within namespaces. They use an allow/deny model with priority-based evaluation.

Policy Model

Each policy specifies:

• Effect: allow or deny
• Actions: what operations the policy covers (e.g., read, write, delete)
• Scope filters: which principals the policy applies to (by role, team, agent class)
• Namespace: which namespace the policy targets (or org-wide if null)
• Priority: higher priority policies are evaluated first

Creating a Policy

curl -X POST https://api.hippocortex.dev/v1/organizations/org_abc123/policies \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "namespaceId": "ns_456",
    "effect": "deny",
    "actions": ["read", "write"],
    "agentClass": "external",
    "priority": 100,
    "description": "Block external agents from customer data"
  }'

Policy Fields

Field	Type	Default	Description
effect	string	required	allow or deny
actions	string[]	["read"]	Actions covered: read, write, delete, admin
namespaceId	string	null	Target namespace (null = org-wide)
teamId	string	null	Applies to members of this team
agentClass	string	null	Applies to agents of this class
role	string	null	Applies to users with this org role
priority	number	0	Higher = evaluated first
conditions	object	{}	Additional match conditions
description	string	null	Human-readable description
isActive	boolean	true	Whether the policy is active

Evaluation Strategy

1. Fetch all active policies for the organization
2. Filter to policies matching the principal's context (role, team, agent class)
3. Sort by priority (highest first)
4. Deny-overrides: any explicit deny at any priority level results in denial
5. If at least one allow matches and no deny matches, access is granted
6. If no policies match, access is granted by default (default_allow)

Deny Always Wins

If a principal matches both an allow and a deny policy, the deny always takes precedence regardless of priority. This prevents accidental data exposure.

Common Policy Examples

Block agents from sensitive data

{
  "namespaceId": "ns_sensitive",
  "effect": "deny",
  "actions": ["read", "write", "delete"],
  "agentClass": "external",
  "priority": 100,
  "description": "No external agents can access sensitive namespace"
}

Allow only engineering team to write

{
  "namespaceId": "ns_codebase",
  "effect": "allow",
  "actions": ["read", "write"],
  "teamId": "team_engineering",
  "priority": 50,
  "description": "Engineering team can read and write codebase memories"
}

Org-wide read access for viewers

{
  "effect": "allow",
  "actions": ["read"],
  "role": "viewer",
  "priority": 10,
  "description": "Viewers can read all org memories"
}

Deny delete for non-admins

{
  "effect": "deny",
  "actions": ["delete"],
  "role": "operator",
  "priority": 200,
  "description": "Only admins and owners can delete memories"
}

Policy Preview / Testing

Before applying a policy, you can test its effect using the evaluate endpoint:

curl -X POST https://api.hippocortex.dev/v1/organizations/org_abc123/policies/evaluate \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "principalType": "agent",
    "principalId": "agt_test",
    "agentClass": "external",
    "action": "read",
    "namespaceId": "ns_456"
  }'

Response:

{
  "ok": true,
  "data": {
    "allowed": false,
    "effect": "deny",
    "matchedPolicyId": "pol_789",
    "evaluatedPolicies": ["pol_789", "pol_012"],
    "allowedNamespaceIds": []
  }
}

This is a dry-run: it evaluates policies but does not perform any actual access.

Listing Policies

curl "https://api.hippocortex.dev/v1/organizations/org_abc123/policies?isActive=true" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123"

Updating a Policy

curl -X PATCH https://api.hippocortex.dev/v1/organizations/org_abc123/policies/pol_789 \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

Deleting a Policy

curl -X DELETE https://api.hippocortex.dev/v1/organizations/org_abc123/policies/pol_789 \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123"