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

Scope	Description
`agents:read`	List and inspect agents
`agents:write`	Register and update agents
`receipts:write`	Mint action receipts
`attestations:read`	Read attestation data
`attestations:write`	Create new attestations
`trust-scores:read`	Read trust score data
`trust-scores:compute`	Trigger trust score recomputation
`delegations:offer`	Offer cross-tenant delegation
`delegations:accept`	Accept delegation offers
`compliance:write`	Create compliance checks
`orchestrations:execute`	Execute multi-agent workflows
`datasets:attest`	Attest dataset provenance
`models:attest`	Attest 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/agent-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

Status	Description
`active`	Session is valid and accepting requests
`expired`	TTL elapsed — automatic cleanup
`terminated`	Explicitly ended by user or system
`suspended`	Paused due to anomaly detection

Terminating a Session

curl -X DELETE https://api.truthlocks.com/v1/agent-sessions/maip-session:01JYYYY \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -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/invoice-generator/invoke \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "session_id": "maip-session:01JYYYY",
    "input": { "order_id": "ord_123", "format": "pdf" }
  }'

Every tool invocation is:

Scope-checked — the session must have the required scope
Rate-limited — per your plan’s tool invocation quota
Audit-logged — full input/output recorded in the audit trail
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.

Principle of least privilege — Request only the scopes needed for the current task
Short-lived sessions — Use the shortest practical TTL (default: 1 hour)
IP allowlisting — Restrict sessions to known network ranges
Rotate credentials — Regenerate agent signing keys on a regular schedule
Monitor trust scores — Set alerts when trust scores drop below thresholds
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.

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

Agent Authorization

Agent Authorization

Authorization Flow

Scope model

Defining Custom Scopes

Built-in Scopes

Session Management

Creating a Session

Session Lifecycle

Terminating a Session

Tool Registration & Invocation

Register a Tool

Invoke a Tool

Security Best Practices

Next steps

MAIP policies

Trust Scores

Cross-Tenant Delegation

​Agent Authorization

​Authorization Flow

​Scope model

​Defining Custom Scopes

​Built-in Scopes

​Session Management

​Creating a Session

​Session Lifecycle

​Terminating a Session

​Tool Registration & Invocation

​Register a Tool

​Invoke a Tool

​Security Best Practices

​Next steps

MAIP policies

Trust Scores

Cross-Tenant Delegation

Agent Authorization

Authorization Flow

Scope model

Defining Custom Scopes

Built-in Scopes

Session Management

Creating a Session

Session Lifecycle

Terminating a Session

Tool Registration & Invocation

Register a Tool

Invoke a Tool

Security Best Practices

Next steps