Attestations

An Attestation is a cryptographically signed, tamper-proof record of every authorization decision. Every allow, block, and request_hold generates an attestation, your tamper-proof audit trail.

··

What is an Attestation?

Every time an agent presents its passport at a gate, the gate evaluates the request and makes a decision: allow, block, or request_hold. That decision is recorded as an Attestation.

Attestations are:

Cryptographically signed, by the gate, using its private key
Tamper-proof, any modification is detectable via signature verification
Immutable, once written, attestations cannot be altered or deleted
Comprehensive, every allow, block, and request_hold is recorded with full context

Unlike application logs (which can be altered by anyone with server access), Modei attestations are cryptographically chained, modification is mathematically detectable.

Attestation Structure

attestation.json

{
  "attestation_id": "att_01HABC...",
  "version": "1.0",
  
  "decision": "allow",
  "timestamp": "2026-02-24T14:30:00Z",
  
  "agent": {
    "agent_id": "research-bot-001",
    "agent_name": "Research Bot",
    "passport_id": "pass_01HXYZ...",
    "issuer_id": "iss_01HABC...",
    "trust_tier": "L2"
  },
  
  "gate": {
    "gate_id": "gate_01HDEF...",
    "gate_name": "Production API Gate"
  },
  
  "request": {
    "action": "web:search",
    "target_domain": "api.example.com",
    "estimated_cost_usd": 0.01
  },
  
  "guardrails_evaluated": [
    { "name": "rate_limit", "result": "pass", "detail": "48/60 requests used this minute" },
    { "name": "spend_limit", "result": "pass", "detail": "$12.50/$100.00 daily spend used" },
    { "name": "domain_allowlist", "result": "pass", "detail": "api.example.com is allowlisted" }
  ],
  
  "signature": {
    "algorithm": "EdDSA",
    "key_id": "gate_01HDEF...",
    "value": "base64url(signature_bytes)"
  },
  
  "chain_hash": "sha256(previous_attestation_id + this_payload)"
}

Why Immutability Matters

Traditional application logs can be altered, someone with database access can delete or modify records. Modei attestations solve this through cryptographic chaining:

Each attestation includes a chain_hash, a hash of the previous attestation plus the current payload
Any modification to a historical attestation breaks the chain, the hash of subsequent records won't match
The gate's signature over the full record means even the platform itself can't silently alter it

This makes Modei attestations suitable for compliance, legal proceedings, and regulated industry requirements where log integrity must be provable.

Reading Your Audit Trail

python

import httpx

client = httpx.Client(
    base_url="https://modei.ai/api/v1",
    headers={"Authorization": "Bearer mod_your_key_here"}
)

# List recent attestations for an agent
response = client.get("/attestations", params={
    "agent_id": "research-bot-001",
    "limit": 50
})
attestations = response.json()

for att in attestations["items"]:
    status = "✅" if att["decision"] == "allow" else "❌"
    print(f"{status} {att['timestamp']}, {att['request']['action']}")

bash

# Via REST API
curl https://modei.ai/api/v1/attestations \
  -H "Authorization: Bearer mod_your_key" \
  -G \
  --data-urlencode "agent_id=research-bot-001" \
  --data-urlencode "limit=50"

Response

{
  "items": [
    {
      "attestation_id": "att_01HABC...",
      "decision": "allow",
      "timestamp": "2026-02-24T14:30:00Z",
      "agent_id": "research-bot-001",
      "action": "web:search",
      "gate_id": "gate_01HDEF..."
    }
  ],
  "total": 1248,
  "page": 1,
  "limit": 50
}

Exporting for Compliance

bash

# Export all attestations for a date range (JSON)
curl "https://modei.ai/api/v1/attestations/export?format=json&after=2026-01-01&before=2026-03-01" \
  -H "Authorization: Bearer mod_your_key" \
  -o audit-report.json

# Export as CSV
curl "https://modei.ai/api/v1/attestations/export?format=csv&agent_id=research-bot-001" \
  -H "Authorization: Bearer mod_your_key" \
  -o audit-report.csv

Exports include the full attestation payload plus cryptographic signatures for verification. Free retains attestations for 30 days, Pro for 1 year, Teams for 3 years. Enterprise supports custom retention periods.

Use Cases

Compliance reporting

Export all agent actions for a period with cryptographic proof of integrity.

Incident investigation

Trace exactly what an agent did, when, and what the gate decided.

Budget auditing

Sum all allowed transactions to verify spend against approved limits.

Proof of authorization

Legal-grade proof that a specific action was authorized (or denied).

Gates, What generates attestations.
Guardrails, The rules evaluated and recorded in each attestation.
Audit Trail API, Full REST API for reading and exporting attestations.

Supravision Anonymous Access