Evaluate MAIP Policy

Evaluate all active agent policies against a specific agent and requested scope

Evaluate MAIP Policy

POST /v1/maip/policies/evaluate

Evaluates all active MAIP policies for the authenticated tenant against a specific agent and requested scope. Returns whether the action is allowed, denied, or requires human approval. This is the runtime enforcement checkpoint that agents call before performing sensitive operations.

Policy evaluation uses a deny-overrides model: if any active policy with a matching deny rule triggers, the action is blocked regardless of any allow rules. The requires_approval flag is additive — it can be set even when the action is allowed.

Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via cookie or JWT claim.

Request Body

agent_id · string · required

MAIP-compliant agent identifier (e.g., "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH"). The agent must exist and belong to the authenticated tenant.

scope · string · required

The permission scope being requested (e.g., "data:write", "tool:execute", "model:train"). Uses the resource:action format defined in Scopes.

action · string

The specific action being performed. Provides additional context for policy rules beyond what the scope communicates.

resource · string

The specific resource being accessed. Provides additional context for audit logging and fine-grained policy conditions.

Evaluation Logic

The evaluation performs three sequential checks:

1. Agent Status Check — The agent must have status: "active". Suspended or revoked agents are always denied.
2. Scope Access Check — The requested scope must be present in the agent’s granted scopes. Explicitly denied scopes (prefixed with !) always block access.
3. Policy Rules Check — All active tenant policies are evaluated in priority order. Each rule’s conditions are AND-ed. If any deny rule matches, the action is blocked.

Response

allowed · boolean

true if the action is permitted, false if denied by any check.

denied_by · string[]

Names of the policies that denied the action. Empty array if allowed.

reason · string

Human-readable reason for denial. One of: - "agent is not active" — Agent is suspended or revoked - "scope not granted to agent" — Scope not in agent’s granted scopes - "denied by policy" — One or more policies blocked the action

requires_approval · boolean

true if any matching policy rule has requires_approval: true, even if the action is otherwise allowed. The caller should present a human approval workflow before proceeding.

Example

curl -X POST https://api.truthlocks.com/v1/maip/policies/evaluate \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH",
    "scope": "data:write",
    "action": "update_customer_record",
    "resource": "customers/cust_12345"
  }'

const response = await fetch(
  "https://api.truthlocks.com/v1/maip/policies/evaluate",
  {
    method: "POST",
    headers: {
      "X-API-Key": "tl_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH",
      scope: "data:write",
      action: "update_customer_record",
      resource: "customers/cust_12345",
    }),
  },
);
const result = await response.json();

if (!result.allowed) {
  console.error(`Denied by: ${result.denied_by.join(", ")}`);
} else if (result.requires_approval) {
  // Route to human approval workflow
}

import requests

response = requests.post(
    "https://api.truthlocks.com/v1/maip/policies/evaluate",
    headers={
        "X-API-Key": "tl_live_...",
        "Content-Type": "application/json",
    },
    json={
        "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH",
        "scope": "data:write",
        "action": "update_customer_record",
        "resource": "customers/cust_12345",
    },
)
result = response.json()