> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create MAIP Policy
> Create a new agent enforcement policy with conditional rules for runtime access control
# Create MAIP Policy
`POST /v1/maip/policies`
Creates a new MAIP agent enforcement policy for the authenticated tenant. Policies define runtime rules that are evaluated when agents request access to scoped resources via the [Evaluate Policy](/api-reference/machine-identity/policies/evaluate) endpoint.
MAIP policies are different from [RBAC issuance
policies](/api-reference/policies/create). MAIP policies govern **machine
agent** behavior at runtime based on trust scores, delegation depth, scopes,
and agent type. RBAC policies govern credential issuance and human user
access.
### Authentication
Requires `X-API-Key` header or Bearer JWT token. Tenant-scoped via cookie or JWT claim.
### Request Body
Human-readable policy name. Used in denial messages and audit logs when the
policy blocks an action. Must be unique per tenant. Maximum 256 characters.
Detailed description of what the policy enforces and why. Maximum 2048
characters.
Policy category for organizational purposes. One of:
* `"scope"` -- Restricts access based on scopes or resources
* `"trust"` -- Restricts access based on trust scores
* `"rate"` -- Restricts access frequency or volume
* `"custom"` -- Custom enforcement logic
Defaults to `"custom"` if omitted.
Evaluation priority. Lower numbers are evaluated first. Range: 1-1000.
Defaults to `100` if omitted. Multiple policies at the same priority are
evaluated in creation order.
JSON array of policy rules. Each rule is evaluated independently. If **any** rule with `"effect": "deny"` matches, the action is denied.
**Rule schema:**
```json theme={null}
{
"conditions": [{ "field": "trust_score", "op": "lt", "value": 0.5 }],
"effect": "deny",
"requires_approval": false
}
```
**Condition fields:**
| Field | Type | Operators | Description |
| ------------------ | ------ | ---------------------------- | -------------------------------------------------------- |
| `trust_score` | number | `lt`, `gt`, `le`, `ge` | Agent's current trust score (0.0-1.0) |
| `scope` | string | `eq`, `ne`, `in`, `contains` | The scope being accessed (e.g., `"data:write"`) |
| `agent_type` | string | `eq`, `ne`, `in` | Agent type (e.g., `"llm"`, `"worker"`, `"orchestrator"`) |
| `delegation_depth` | number | `gt`, `ge`, `lt`, `le` | Agent's position in the delegation chain (0 = direct) |
**Operators:**
| Operator | Description | Example value |
| ---------- | --------------------------- | ------------------- |
| `eq` | Equals | `"data:write"` |
| `ne` | Not equals | `"system"` |
| `lt` | Less than | `0.5` |
| `gt` | Greater than | `3` |
| `le` | Less than or equal | `0.3` |
| `ge` | Greater than or equal | `0.7` |
| `in` | Matches any value in a list | `["llm", "worker"]` |
| `contains` | String contains substring | `"write"` |
**Effects:**
* `"allow"` -- Explicitly allow (does not override denials)
* `"deny"` -- Block the action. First deny wins.
* `"require_approval"` -- Require human approval before proceeding
All conditions within a single rule are AND-ed. Multiple rules within a policy are evaluated independently.
### Response
Returns the created policy object with server-generated fields (`id`, `tenant_id`, `status`, timestamps).
UUID primary key of the created policy.
UUID of the owning tenant.
Policy name as provided.
Policy description, if provided.
Policy category.
Always `"active"` on creation.
Evaluation priority.
The rules array as provided.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
### Example
```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/maip/policies \
-H "X-API-Key: tl_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Block Low-Trust Write Operations",
"description": "Deny data:write scope access for agents with trust score below 0.5",
"category": "trust",
"priority": 10,
"rules": [
{
"conditions": [
{"field": "trust_score", "op": "lt", "value": 0.5},
{"field": "scope", "op": "eq", "value": "data:write"}
],
"effect": "deny",
"requires_approval": false
}
]
}'
```
```javascript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/maip/policies", {
method: "POST",
headers: {
"X-API-Key": "tl_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Block Low-Trust Write Operations",
description:
"Deny data:write scope access for agents with trust score below 0.5",
category: "trust",
priority: 10,
rules: [
{
conditions: [
{ field: "trust_score", op: "lt", value: 0.5 },
{ field: "scope", op: "eq", value: "data:write" },
],
effect: "deny",
requires_approval: false,
},
],
}),
});
const policy = await response.json();
```
```python theme={null}
import requests
response = requests.post(
"https://api.truthlocks.com/v1/maip/policies",
headers={
"X-API-Key": "tl_live_...",
"Content-Type": "application/json",
},
json={
"name": "Block Low-Trust Write Operations",
"description": "Deny data:write scope access for agents with trust score below 0.5",
"category": "trust",
"priority": 10,
"rules": [
{
"conditions": [
{"field": "trust_score", "op": "lt", "value": 0.5},
{"field": "scope", "op": "eq", "value": "data:write"},
],
"effect": "deny",
"requires_approval": False,
}
],
},
)
policy = response.json()
```
## OpenAPI
````yaml mint-openapi.yaml POST /v1/maip/policies
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/maip/policies:
post:
tags:
- Machine Identity
summary: Create MAIP Policy
description: >
Creates a new MAIP agent enforcement policy. Policies define runtime
rules
evaluated when agents request access to scoped resources.
operationId: maip.policies.create
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- rules
properties:
name:
type: string
maxLength: 256
description: Human-readable policy name
description:
type: string
maxLength: 2048
description: Detailed description of the policy
category:
type: string
enum:
- scope
- trust
- rate
- custom
default: custom
description: Policy category
priority:
type: integer
minimum: 1
maximum: 1000
default: 100
description: Evaluation priority (lower = first)
rules:
type: array
items:
$ref: '#/components/schemas/MaipPolicyRule'
description: Array of policy rules
responses:
'201':
description: Policy created
content:
application/json:
schema:
$ref: '#/components/schemas/MaipPolicy'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- APIKey: []
components:
schemas:
MaipPolicyRule:
type: object
properties:
conditions:
type: array
items:
$ref: '#/components/schemas/MaipPolicyCondition'
description: Conditions that must all match (AND logic)
effect:
type: string
enum:
- allow
- deny
- require_approval
description: Action to take when conditions match
requires_approval:
type: boolean
description: Whether human approval is required
MaipPolicy:
type: object
properties:
id:
type: string
format: uuid
description: UUID primary key
tenant_id:
type: string
format: uuid
description: UUID of the owning tenant
name:
type: string
description: Human-readable policy name
description:
type: string
description: Detailed policy description
category:
type: string
enum:
- scope
- trust
- rate
- custom
description: Policy category
status:
type: string
enum:
- active
- disabled
- archived
description: Policy lifecycle status
priority:
type: integer
description: Evaluation priority (lower = first)
rules:
type: array
items:
$ref: '#/components/schemas/MaipPolicyRule'
description: Array of policy rules
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
MaipPolicyCondition:
type: object
properties:
field:
type: string
enum:
- trust_score
- scope
- agent_type
- delegation_depth
description: The field to evaluate
op:
type: string
enum:
- eq
- ne
- lt
- gt
- le
- ge
- in
- contains
description: Comparison operator
value:
description: Value to compare against (type depends on field)
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````