# Avatron — Complete Documentation # Version: 1.1 | February 2026 | Standard Logic Co. # Generated: 2026-02-28 > Avatron is the trust and control layer for AI agents — providing cryptographic identity > (passports), policy enforcement (gates + guardrails), and a tamper-proof audit trail. > Built by Standard Logic Co. > > Every documentation page supports Copy as Markdown for use with AI assistants. --- ## What is Avatron? Avatron gives AI agents a verified identity and enforces rules about what they can and cannot do — so operators stay in control even when agents are working autonomously. ### The Problem AI agents are increasingly taking consequential actions: booking travel, executing trades, sending emails, provisioning infrastructure, processing payments. They do this autonomously, at scale. And today's AI agents have NO verified identity. When an agent makes a purchase, executes a trade, or sends a message on your behalf, there is no cryptographic record of what authorized it to do so. No audit trail. No spend controls. No way to prove the agent acted within intended scope. ### The Solution Avatron provides three interlocking capabilities: 1. **Cryptographic Agent Identity (Passports)** — Ed25519 keypairs. The private key is generated client-side and never stored on Avatron servers. Identity verification is decentralized, fast, and offline-capable. 2. **Policy Enforcement (Gates + Guardrails)** — Real-time enforcement points that block non-compliant requests before they execute. Rate limits, spend caps, domain allowlists, PII controls, approval workflows. 3. **Immutable Audit Trail (Attestations)** — Every allow and deny generates a cryptographically signed, tamper-proof record. Any modification is mathematically detectable. ### Key Analogy Think of it like a **driver's license + insurance policy** for your AI agent: - The **driver's license** (Passport) proves who the agent is and that they're authorized. - The **insurance policy** (Gate + Guardrails) defines limits and flags out-of-bounds behavior. --- ## Core Concepts ### Issuers An Issuer is your signing identity — the organizational stamp that proves you authorized an agent's passport. Every passport traces back to an issuer, establishing provenance and trust. **Trust Tiers:** - **L1 — Self:** Self-issued, no account required. Generated locally via the Avatron SDK. For development, testing, personal use. Quick setup, no external verification. Example: `pip install avatron` then create a local issuer with domain `dev.local`. - **L2 — Internal:** Managed platform issuer. Created through the Avatron dashboard or API. Domain ownership verified at creation. For production deployments. - **L3 — Verified/Certified:** Third-party verified. Enterprise-grade certification. Required for regulated industries (finance, healthcare, legal). Coming Q2 2026. **How to create an issuer (dashboard):** 1. Dashboard → Issuers → Create Issuer 2. Enter name and domain (e.g., "Acme Corp", "acmecorp.com") 3. Choose trust tier (L1 or L2) 4. Click Create **API:** POST /v1/issuers with {"name": "...", "domain": "...", "trust_tier": "L2"} --- ### Passports A Passport is a cryptographically signed credential that proves an agent's identity and authorized permissions. Built on Ed25519 keypairs. **What's inside a passport:** - Unique agent ID and name - Issuing organization's identity (issuer ID + domain) - Set of permissions (what the agent is authorized to do) - Expiry date - Ed25519 public key (private key never stored server-side) - Optional metadata **Permissions format:** String scopes like `web:search`, `email:read`, `payments:*`, `mcp:*`, `*`. Wildcards supported: `payments:*` covers all payment sub-actions. **Private Key Rules:** - Generated client-side, shown ONCE, never stored by Avatron - Save to password manager (1Password, Bitwarden, Keychain) immediately - Never hardcode, email, or paste in chat - Revoke and reissue if lost **API:** POST /v1/passports — Issues a passport (returns private_key ONCE) GET /v1/passports — Lists all passports GET /v1/passports/:id — Gets passport details GET /v1/passports/:id/verify — Verifies validity POST /v1/passports/:id/revoke — Revokes immediately --- ### Gates A Gate is a security checkpoint that verifies agent passports and enforces guardrails in real time. Gates block non-compliant requests before they execute. **What a gate does on each request:** 1. Verify the Ed25519 passport signature 2. Check the issuer (is it trusted for the configured trust level?) 3. Check expiry and revocation status 4. Evaluate guardrails (rate limits, spend limits, domain rules, etc.) 5. Decide: allow or deny 6. Issue an attestation (signed, tamper-proof audit record) **Security levels:** L1 — Development: - Accepts self-issued passports - Basic nonce checking - Revocation optional L2 — Production: - Managed issuers only - Strict replay protection (nonce + timestamp, 5-minute window) - Mandatory revocation check on every request L3 — High Assurance (coming Q2 2026): - Verified/certified issuers only - Proof of Possession (challenge-response) - Mandatory CRL check **API:** POST /v1/gates — Create a gate GET /v1/gates — List gates GET /v1/gates/:id — Get gate details + stats PUT /v1/gates/:id — Update gate configuration DELETE /v1/gates/:id — Delete gate POST /v1/gates/:id/test — Test a gate with a passport token --- ### Guardrails Guardrails are configurable rule sets attached to gates. They evaluate every request in real time and block non-compliant actions before they execute. **Types of guardrails:** Rate Limits: Cap requests per minute, hour, or day. {"rate_limits": {"requests_per_minute": 60, "requests_per_day": 10000}} Spend Caps: Hard dollar limits per transaction, day, or month. {"spend_limits": {"daily_usd": 100.00, "per_transaction_usd": 10.00}} Domain Allowlists: Only allow specific external domains. {"allowed_domains": ["api.example.com", "data.example.com"]} PII Controls: Detect and control PII in requests. {"pii_controls": {"mode": "block" | "redact" | "log_only" | "encrypt"}} Approval Workflows: Require human approval for specific thresholds. {"approval_workflows": {"require_approval_above_usd": 100.00}} Permission Scopes: Only allow actions matching declared passport permissions. **Evaluation order:** 1. Permission scope check 2. Rate limit check 3. Spend limit check 4. Domain allowlist check 5. PII detection 6. Approval workflow check → All pass: ALLOW + attestation → Any fail: DENY + attestation with reason --- ### Trust Profiles L1 (Development/Self): - No account required - Self-issued passports via local Avatron SDK - Basic replay protection - Optional revocation - Best for: dev, testing, personal automation L2 (Production/Internal): - Managed platform account required - Domain verified - Strict nonce + timestamp replay protection - Mandatory revocation check - Best for: production, team deployments, real APIs L3 (High Assurance/Certified) — Coming Q2 2026: - Third-party verified issuer - Proof of Possession (PoP) required - Mandatory CRL check - Best for: finance, healthcare, legal, regulated industries --- ### Attestations An Attestation is a cryptographically signed, tamper-proof record of every authorization decision. Every allow AND every deny generates an attestation. **Attestation structure:** { "attestation_id": "att_01HABC...", "decision": "allow" | "deny", "timestamp": "2026-02-24T14:30:00Z", "agent": { "agent_id": "research-bot-001", "passport_id": "pass_01HXYZ...", "trust_tier": "L2" }, "gate": { "gate_id": "gate_01HDEF..." }, "request": { "action": "web:search", "target_domain": "api.example.com" }, "guardrails_evaluated": [...], "signature": { "algorithm": "EdDSA", "value": "base64url..." }, "chain_hash": "sha256:..." // Links to previous attestation } **Why immutability matters:** 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, making tampering mathematically detectable. Unlike application logs, Avatron attestations cannot be silently altered by anyone — not even the platform itself. **API:** GET /v1/attestations — List with filters (agent_id, gate_id, decision, after, before) GET /v1/attestations/:id — Get single attestation with full signature GET /v1/attestations/export — Export JSON or CSV with cryptographic signatures --- ## Agent Autonomy Guide ### The Bootstrap Problem Every autonomous agent system has a bootstrap problem: someone has to set things up before the agent can operate autonomously. **Minimal human intervention required (ONCE):** 1. Create a Avatron account at app.avatron.co 2. Create an Issuer 3. Generate an API key with scopes: passports:issue, passports:read, gates:read 4. Provide the API key to the agent via environment variable **What the agent can do forever after:** - Issue new passports for itself or sub-agents - Rotate credentials before expiry - Create and configure gates - Verify other agents' passports - Read its own audit trail - Self-manage within the issuer's trust level ### Path A: Self-Issued L1 Passports (No Account Required) Installation: pip install avatron npm install avatron-sdk Python example: from avatron import PassportIssuer, TrustTier from datetime import timedelta issuer = PassportIssuer.create_local(name="my-issuer", domain="dev.local") passport = issuer.issue_passport( agent_id="research-bot-001", agent_name="Research Bot", permissions=["web:search", "web:fetch"], trust_tier=TrustTier.L1, expires_in=timedelta(days=30) ) # Save private_key to password manager immediately! passport.save_credentials("~/.config/my-agent/credentials.json") TypeScript example: import { PassportIssuer, TrustTier } from 'avatron-sdk'; const issuer = await PassportIssuer.createLocal({ name: 'my-issuer', domain: 'dev.local' }); const passport = await issuer.issuePassport({ agentId: 'research-bot-001', permissions: ['web:search', 'web:fetch'], trustTier: TrustTier.L1, expiresInDays: 30, }); // Save passport.privateKey immediately! ### Path B: Managed Platform via API Key Environment setup: export AVATRON_API_KEY="avt_your_key_here" export AVATRON_ISSUER_ID="iss_your_issuer_id" Issue a passport via API: POST https://api.avatron.co/v1/passports Authorization: Bearer avt_your_key_here Body: { "issuer_id": "iss_...", "agent_id": "research-bot-001", "agent_name": "Research Bot", "permissions": ["web:search", "web:fetch"], "expires_in_days": 30, "trust_tier": "L2" } Response includes "private_key" — save immediately to secrets manager! API key scopes: passports:issue, passports:read, passports:revoke, gates:create, gates:read, gates:update, gates:manage, issuers:create, issuers:read, issuers:update, templates:read, osgate:read, osgate:manage, admin:* ### Path C: MCP Server Integration (OAuth 2.0 PKCE) The Avatron MCP server has 21 tools. No client secret needed (PKCE is public-client safe). Configure Claude Desktop: { "mcpServers": { "avatron": { "command": "npx", "args": ["-y", "avatron-mcp"], "env": { "AVATRON_API_KEY": "avt_your_key_here", "AVATRON_ISSUER_ID": "iss_your_issuer_id" } } } } Available MCP tools (21): Passports: issue_passport, get_passport, list_passports, revoke_passport, verify_passport Gates: create_gate, get_gate, list_gates, update_gate, delete_gate, test_gate Attestations: list_attestations, get_attestation, export_audit_trail Issuers: create_issuer, get_issuer, list_issuers Templates: list_templates, get_template, apply_template OS Gate: get_osgate_sessions, manage_osgate ### Agent-to-Agent Trust Chains Orchestrator agents can spawn sub-agents with delegated (never elevated) permissions. Structure: Orchestrator Agent (L2 Passport, permissions: *) ├── Research Agent (L1 Passport, permissions: web:search, web:fetch) ├── Writer Agent (L1 Passport, permissions: documents:write) └── Reviewer Agent (L1 Passport, permissions: documents:read) Rules: - Sub-agents CANNOT have more permissions than the parent - Sub-agent passports should have short TTLs (task-scoped) - Revoke sub-agent passports when task is complete - metadata.spawned_by should record parent agent_id for audit ### Auto-Rotation Before Expiry from datetime import datetime, timedelta from avatron import AgentCredentials async def ensure_valid(creds_path, issuer): creds = AgentCredentials.load(creds_path) if creds.expires_at < datetime.utcnow() + timedelta(days=7): new = issuer.issue_passport( agent_id=creds.agent_id, agent_name=creds.agent_name, permissions=creds.permissions, trust_tier=creds.trust_tier, expires_in_days=30 ) new.save_credentials(creds_path) return AgentCredentials.load(creds_path) return creds ### Verifying Incoming Agent Passports from avatron import PassportVerifier verifier = PassportVerifier(trusted_issuer_domains=["avatron.co", "yourcompany.ai"]) result = await verifier.verify(passport_token) Check: result.valid, result.expired, result.revoked, result.trust_tier, result.permissions --- ## SDK Reference ### Python SDK Install: pip install avatron Requires: Python 3.9+, httpx, cryptography, python-jose Key classes: - PassportIssuer — Create local or managed issuers, issue passports - PassportClient — HTTP client that auto-signs requests with passport headers - AgentCredentials — Load/save credentials, check expiry - PassportVerifier — Verify incoming agent passports - AvatronClient — Full platform API client (requires API key) Request headers automatically added by PassportClient: - X-Avatron-Agent-ID: - X-Avatron-Passport: - X-Avatron-Signature: ### TypeScript SDK Install: npm install avatron-sdk (also: yarn add, pnpm add) Requires: Node.js 18+, supports ESM and CommonJS Key exports: - PassportIssuer — Create local or managed issuers - PassportClient — Signed HTTP client - AgentCredentials — Load/save/check credentials - PassportVerifier — Verify incoming passports - TrustTier — L1 | L2 | L3 enum ### MCP Integration Install: npx avatron-mcp (interactive setup CLI) Manual: npm install -g avatron-mcp Environment variables: - AVATRON_API_KEY (required) - AVATRON_ISSUER_ID (required) - AVATRON_API_BASE (optional override) - AVATRON_MCP_LOG_LEVEL (optional: debug|info|warn|error) --- ## REST API Reference Base URL: https://api.avatron.co/v1 Authentication: Authorization: Bearer avt_ ### Passports POST /passports Issue a passport (private_key returned ONCE) GET /passports List passports (filter: issuer_id, status, trust_tier) GET /passports/:id Get passport GET /passports/:id/verify Verify passport validity and revocation status POST /passports/:id/revoke Revoke a passport (immediate) ### Gates POST /gates Create a gate with guardrail configuration GET /gates List gates with stats GET /gates/:id Get gate with full constraint config and stats PUT /gates/:id Update gate constraints DELETE /gates/:id Delete gate POST /gates/:id/test Test verification (returns decision + attestation_id) ### Issuers POST /issuers Create an issuer GET /issuers List issuers (filter: trust_tier) GET /issuers/:id Get issuer with passport stats PUT /issuers/:id Update issuer name/metadata (domain immutable) ### Attestations GET /attestations List with filters: agent_id, gate_id, decision, after, before GET /attestations/:id Get single attestation with signature GET /attestations/export Export JSON or CSV (large exports streamed) ### Templates GET /templates List all templates GET /templates/:id Get template with full JSON config POST /templates Create custom template ### Error Codes 200 — Success 201 — Created 400 — Bad request 401 — Missing/invalid API key 403 — Insufficient scope 404 — Not found 409 — Conflict (duplicate agent_id, etc.) 429 — Rate limited 500 — Server error --- ## Template Library (30 Templates) ### Personal Productivity (6) 1. Personal Email Agent (L1, $0/day) - Permissions: email:read, email:send, email:draft - Rate: 10 sends/hour, 50 sends/day - Requires approval for new contacts 2. Calendar Manager (L1, $0/day) - Permissions: calendar:read, calendar:write, calendar:invite - 20 events/day, 10 external invites/day, no deletes 3. File Organizer (L1, $0/day) - Permissions: files:read, files:write, files:move - Scoped to configured directories, no deletes, no system files 4. Note-Taking Agent (L1, $2/day) - Permissions: notes:read, notes:write, audio:transcribe - 100 notes/day, external calls to api.openai.com allowed 5. Task Manager (L1, $0/day) - Permissions: tasks:read, tasks:write, tasks:assign - 200 tasks/day, no delete, approval required for cross-person assigns 6. Personal Shopper (L2, $50/day) - Permissions: web:search, commerce:purchase, commerce:cart - $25 per transaction, $200/month, approval above $20, approved merchants only ### Business Operations (6) 7. Customer Support Agent (L2, $500/day) - Permissions: support:read, support:respond, orders:read, refunds:issue - $50/ticket refund authority, auto-escalate above, 100 tickets/hour 8. Sales Development Agent (L2, $10/day) - Permissions: web:search, crm:read, crm:write, email:send - 100 emails/day, max 3 follow-ups, no pricing commitments, honor opt-outs 9. HR Onboarding Agent (L2, $0/day) - Permissions: hr:onboarding, accounts:provision, training:assign, email:send - No salary data, no record modification, GDPR mode, internal email only 10. Contract Review Agent (L2, $5/day) - Permissions: documents:read, analysis:run, reports:write - No signing, no modification, no external transmission 11. Expense Report Agent (L2, $0/day) - Permissions: expenses:read, expenses:create, expenses:submit - No approval authority, receipt required above $25, flag above $500 12. Meeting Scheduler (L2, $0/day) - Permissions: calendar:read, calendar:write, calendar:invite, rooms:book - 50 external invites/day, 10 room bookings/day, approval for short-notice cancels ### Developer Tools (6) 13. Code Review Agent (L2, $5/day) - Permissions: code:read, prs:comment, issues:create - No merge, no approve, no push, 50 comments/hour 14. CI/CD Agent (L2, $20/day) - Permissions: pipelines:read, pipelines:trigger, deployments:staging - dev/staging/qa only, no production deploy, no pipeline config changes 15. Documentation Generator (L2, $3/day) - Permissions: code:read, docs:write, web:fetch - Docs directories only, no source code write, review before publish 16. Bug Triage Agent (L2, $5/day) - Permissions: issues:read, issues:write, issues:assign, sandbox:run - No close issues, isolated sandbox, no network in sandbox 17. Dependency Auditor (L2, $1/day) - Permissions: code:read, packages:read, reports:write, web:fetch - No dependency updates, allowed: nvd.nist.gov, osv.dev, registry.npmjs.org 18. Security Scanner (L3, $5/day) - Permissions: code:read, infra:read, reports:write - No code/infra modification, no external transmission, immutable findings log ### Finance & Commerce (6) 19. Budget Tracker (L2, $0/day) - Permissions: finance:read, reports:write, notifications:send - No transactions, masked account numbers, no external financial data 20. Invoice Processor (L2, $0/day) - Permissions: documents:read, invoices:process, payments:read, approvals:route - No payment initiation, duplicate detection, flag above $50K 21. Financial Research Agent (L2, $10/day) - Permissions: web:search, web:fetch, finance:market_data, reports:write - No trading, no brokerage connections, internal reports only 22. Crypto Trading Agent — Strict (L3, $5,000/day) - Permissions: crypto:read, crypto:trade, crypto:portfolio - $1K/trade, $5K/day, approved pairs only (BTC/ETH/SOL), stop-loss required, no leverage, no withdrawal, immutable trade log, real-time alerts 23. Payroll Assistant (L3, $0/day) - Permissions: hr:read, payroll:read, payroll:prepare, reports:write - No payroll execution, no pay rate modification, encrypted PII, masked SSN 24. Subscription Manager (L2, $0/day) - Permissions: subscriptions:read, subscriptions:cancel, subscriptions:modify - Auto-cancel below $20/month, approval above $50/month new sub, no upgrades ### Research & Content (6) 25. Web Research Agent (L1, $3/day) - Permissions: web:search, web:fetch, documents:write - 500 pages/day, 60 searches/hour, no form submission, 10MB download limit 26. Content Writer (L1, $5/day) - Permissions: documents:write, web:search, assets:read - No autonomous publish, plagiarism check, link review required 27. Social Media Manager (L2, $0/day) - Permissions: social:read, social:post, social:reply - 10 posts/day/platform, 20 replies/hour, escalate above 5K engagements 28. Data Analyst (L2, $10/day) - Permissions: data:read, analysis:run, reports:write, dashboards:create - No data write, no external raw export, 5-minute query timeout, PII masked 29. Market Research Agent (L2, $50/day) - Permissions: web:search, web:fetch, surveys:read, reports:write - Approval above $50 purchase, no competitor contact, internal reports 30. Competitive Intelligence Agent (L2, $10/day) - Permissions: web:search, web:fetch, monitoring:create, reports:write - No competitor contact, public data only, 365-day retention, real-time alerts --- ## Pricing Free — Local Enforcement - Self-issued L1 passports (open-source Avatron SDK) - Local gate enforcement, no dashboard - No attestation storage - Unlimited developer use Pro — $12/month per user - Full dashboard (issuers, passports, gates, attestations) - 90-day attestation retention - Mobile approval workflows - Up to 10 agent passports - Email + webhook alerts Teams — $12/user/month - Everything in Pro - Team issuer management - Up to 100 agent passports per seat - 365-day attestation retention - RBAC, priority support Enterprise — Custom pricing - Unlimited agents and gates - L3 trust tier - Custom retention and compliance export - SSO/SAML - On-premises deployment option - Custom template development --- ## Discovery Avatron follows the llms.txt convention for machine-readable discovery. Agents can autonomously discover integration details by fetching: GET https://avatron.co/llms.txt --- ## About Built by Standard Logic Co. Website: avatron.co Dashboard: app.avatron.co Protocol: Open standards (Ed25519, JWT, MCP) Support: support@avatron.co API Launch: January 2026 MCP Server Launch: January 2026 (21 tools) Commerce Layer Launch: February 2026 Patent Portfolio: 30+ patents (cryptographic agent identity, bilateral metering, policy enforcement) --- Last updated: February 2026