Skip to main content

​
Agent Authorization

Every AI agent in the Truthlocks platform operates under a strict authorization model. Agents must be registered, assigned scopes, and create time-bounded sessions before they can take any action.

​
Authorization Flow

Register Agent → Assign Scopes → Create Session → Execute Actions → Terminate Session
      │               │                │                │               │
      ▼               ▼                ▼                ▼               ▼
  agent_id        scope_ids       session_token    audit_logged      cleanup
All agent authorization endpoints — scopes, sessions, and tools — have an interactive API playground. Open any endpoint in the Agent Sessions & Tools API reference and click Send to try it against the Sandbox.

​
Scope model

Scopes follow a hierarchical resource:action pattern. When an agent requests a session, it can only request scopes that were assigned at registration.

​
Defining Custom Scopes

curl -X POST https://api.truthlocks.com/v1/scopes \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "name": "invoices:approve",
    "description": "Approve invoices up to configured threshold",
    "constraints": {
      "max_amount_cents": 500000,
      "require_dual_approval_above": 100000
    }
  }'

​
Built-in Scopes

ScopeDescription
agents:readList and inspect agents
agents:writeRegister and update agents
receipts:writeMint action receipts
attestations:readRead attestation data
attestations:writeCreate new attestations
trust-scores:readRead trust score data
trust-scores:computeTrigger trust score recomputation
delegations:offerOffer cross-tenant delegation
delegations:acceptAccept delegation offers
compliance:writeCreate compliance checks
orchestrations:executeExecute multi-agent workflows
datasets:attestAttest dataset provenance
models:attestAttest model lineage

​
Session Management

Sessions provide time-bounded execution contexts with automatic expiry and optional IP allowlisting.

​
Creating a Session

curl -X POST https://api.truthlocks.com/v1/sessions \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "scopes": ["receipts:write", "attestations:read"],
    "ttl_seconds": 3600,
    "ip_allowlist": ["10.0.0.0/8"],
    "metadata": {
      "task": "process-quarterly-invoices",
      "initiated_by": "user:alice@corp.com"
    }
  }'
Response: 
{
  "id": "maip-session:01JYYYY",
  "agent_id": "maip-agent:01JXXXX",
  "token": "mst_live_...",
  "scopes": ["receipts:write", "attestations:read"],
  "expires_at": "2026-04-06T13:00:00Z",
  "status": "active"
}

​
Session Lifecycle

StatusDescription
activeSession is valid and accepting requests
expiredTTL elapsed — automatic cleanup
terminatedExplicitly ended by user or system
suspendedPaused due to anomaly detection

​
Terminating a Session

curl -X POST https://api.truthlocks.com/v1/sessions/maip-session:01JYYYY/terminate \
  -H "X-API-Key: $API_KEY" \
  -d '{ "reason": "Task completed" }'

​
Tool Registration & Invocation

Agents can register tools they expose and invoke tools registered by other agents (subject to scope checks).

​
Register a Tool

curl -X POST https://api.truthlocks.com/v1/tools \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "name": "generate-invoice",
    "description": "Generate PDF invoice from order data",
    "input_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "format": { "type": "string", "enum": ["pdf", "html"] }
      },
      "required": ["order_id"]
    }
  }'

​
Invoke a Tool

curl -X POST https://api.truthlocks.com/v1/tools/maip-tool:01JZZZZ/invoke \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "session_id": "maip-session:01JYYYY",
    "input": { "order_id": "ord_123", "format": "pdf" }
  }'
Every tool invocation is:
  1. Scope-checked — the session must have the required scope
  2. Rate-limited — per your plan’s tool invocation quota
  3. Audit-logged — full input/output recorded in the audit trail
  4. Metered — counted against your billing entitlements

​
Security Best Practices

Never embed session tokens in client-side code. Session tokens grant the full scope of the session and should be treated as secrets.
  1. Principle of least privilege — Request only the scopes needed for the current task
  2. Short-lived sessions — Use the shortest practical TTL (default: 1 hour)
  3. IP allowlisting — Restrict sessions to known network ranges
  4. Rotate credentials — Regenerate agent signing keys on a regular schedule
  5. Monitor trust scores — Set alerts when trust scores drop below thresholds
  6. Use the kill switch — Immediately revoke compromised agents

​
Next steps

MAIP policies

Runtime enforcement rules based on trust scores, scopes, and delegation depth.

Trust Scores

Continuous behavioral trust evaluation for agents.

Cross-Tenant Delegation

Allow agents to act across organizational boundaries.