> ## 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.

# Agent Authorization

> Scope-based authorization, session management, and tool invocation for AI agents.

# 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
```

<Tip>
  All agent authorization endpoints — scopes, sessions, and tools — have an interactive API playground. Open any endpoint in the [Agent Sessions & Tools](/api-reference/machine-identity/sessions/create) API reference and click **Send** to try it against the Sandbox.
</Tip>

## 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

```bash theme={null}
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

```bash theme={null}
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:**

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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:

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

<Warning>
  Never embed session tokens in client-side code. Session tokens grant the full scope of the session and should be treated as secrets.
</Warning>

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

<CardGroup cols={2}>
  <Card title="MAIP policies" href="/guides/maip-policies" icon="shield-halved">
    Runtime enforcement rules based on trust scores, scopes, and delegation depth.
  </Card>

  <Card title="Trust Scores" href="/guides/trust-scores" icon="chart-line">
    Continuous behavioral trust evaluation for agents.
  </Card>

  <Card title="Cross-Tenant Delegation" href="/guides/cross-tenant-delegation" icon="arrow-right-arrow-left">
    Allow agents to act across organizational boundaries.
  </Card>
</CardGroup>