Skip to main content
POST
/
v1
/
maip
/
policies
/
evaluate
Evaluate MAIP Policy
curl --request POST \
  --url https://api.truthlocks.com/v1/maip/policies/evaluate \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_id": "<string>",
  "scope": "<string>",
  "action": "<string>",
  "resource": "<string>"
}
'
{
  "allowed": true,
  "denied_by": [
    "<string>"
  ],
  "reason": "<string>",
  "requires_approval": true
}

​
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()

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
agent_id
string
required

MAIP-compliant agent identifier

​
scope
string
required

Permission scope being requested

​
action
string

Specific action being performed

​
resource
string

Specific resource being accessed

Response

Evaluation result

​
allowed
boolean

Whether the action is permitted

​
denied_by
string[]

Names of policies that denied the action

​
reason
string

Human-readable denial reason

​
requires_approval
boolean

Whether human approval is required