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

# Trust Scores

> Continuous behavioral trust evaluation for AI agents with configurable scoring factors.

# Trust Scores

Trust scores provide a **continuous, real-time assessment** of an AI agent's behavioral reliability. Every agent in the Truthlocks platform receives a score from 0 to 100, updated after each action.

## How It Works

```
Agent Action → Event Logged → Score Recomputed → Policy Evaluated
                                    │
                              ┌─────┴─────┐
                              │ Score: 87  │
                              │ Trend: ↑   │
                              └────────────┘
                                    │
                        ┌───────────┼───────────┐
                        ▼           ▼           ▼
                    No Action   Alert Team   Suspend Agent
                   (score > 70) (50 < s < 70) (score < 50)
```

<Tip>
  All trust score and witness endpoints have an interactive API playground. Open any endpoint in the [Trust & Witness](/api-reference/machine-identity/trust-scores/get) API reference and click **Send** to try it live.
</Tip>

## Scoring factors

| Factor                  | Default Weight | Description                                               |
| ----------------------- | -------------- | --------------------------------------------------------- |
| `behavioral_compliance` | 35%            | Actions stay within declared scope boundaries             |
| `scope_adherence`       | 25%            | No attempts to access unauthorized resources              |
| `anomaly_score`         | 20%            | Statistical deviation from historical behavior patterns   |
| `peer_attestations`     | 10%            | Other agents in the witness network vouch for behavior    |
| `session_hygiene`       | 10%            | Proper session lifecycle (creation, renewal, termination) |

## Reading Trust Scores

### Get Current Score

```bash theme={null}
curl https://api.truthlocks.com/v1/trust-scores/maip-agent:01JXXXX \
  -H "X-API-Key: $API_KEY"
```

```json theme={null}
{
  "agent_id": "maip-agent:01JXXXX",
  "score": 87,
  "factors": {
    "behavioral_compliance": 92,
    "scope_adherence": 95,
    "anomaly_score": 12,
    "peer_attestations": 78,
    "session_hygiene": 90
  },
  "trend": "stable",
  "computed_at": "2026-04-06T12:00:00Z"
}
```

### Get Score History

```bash theme={null}
curl "https://api.truthlocks.com/v1/trust-scores/maip-agent:01JXXXX/history?period=7d" \
  -H "X-API-Key: $API_KEY"
```

### Force Recomputation

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/trust-scores/maip-agent:01JXXXX/compute \
  -H "X-API-Key: $API_KEY"
```

## Configuring Thresholds

| Threshold | Recommended Action                                            |
| --------- | ------------------------------------------------------------- |
| 90-100    | Full autonomy — agent operates without intervention           |
| 70-89     | Standard operation — normal monitoring                        |
| 50-69     | Enhanced monitoring — alert team, increase logging verbosity  |
| 30-49     | Restricted mode — require human approval for critical actions |
| 0-29      | Automatic suspension — kill switch triggered                  |

## Witness Network

Agents can participate in a **witness network** where peers attest to each other's behavior.

### Create a Witness Request

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/witness/request \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "subject_agent_id": "maip-agent:01JXXXX",
    "claim": "Completed invoice processing without errors",
    "evidence": { "task_id": "task_456", "records_processed": 150 }
  }'
```

### Attest as Witness

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/witness/maip-witness:01JWWWW/attest \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "attestor_agent_id": "maip-agent:01JBBBB",
    "verdict": "confirmed",
    "confidence": 0.95
  }'
```

### Consensus

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/witness/maip-witness:01JWWWW/consensus \
  -H "X-API-Key: $API_KEY"
```

```json theme={null}
{
  "witness_id": "maip-witness:01JWWWW",
  "consensus": "confirmed",
  "confidence": 0.91,
  "attestations": 4,
  "quorum_met": true
}
```

## Integration with Risk Engine

Trust scores feed directly into the Truthlocks risk evaluation engine. Low trust scores automatically increase the risk signal for any action the agent takes:

```
Trust Score < 50 → Risk Signal: HIGH → Action blocked or requires approval
```

## Usage metering

Each on-demand trust score computation increments the `maip.trust_computes` usage counter for your billing cycle. Background score updates triggered by the platform (such as after agent actions) also count toward this metric.

You can monitor your consumption with the [usage API](/api-reference/billing/usage) or in the console at **Settings > Billing > Usage** under the **MAIP** section.

<Info>
  Trust score compute quotas vary by plan tier. See the [billing overview](/billing/overview#metered-products) for details on all MAIP metered products.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Machine Identity" href="/guides/machine-identity" icon="fingerprint">
    Full overview of the Machine Agent Identity Protocol.
  </Card>

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