APort

AI Passport Registry Documentation

This directory contains comprehensive documentation for the AI Passport Registry system, including API specifications, implementation guides, and code examples.

🚀 Start Here

📖 Developer Guide - START HERE!

Your complete guide to integrating AI agent verification, policy enforcement, and MCP support. Includes quick start, API reference, middleware setup, and best practices.

📚 Documentation Structure

Core Documentation

Developer Resources

🚀 Quick Start

1. Verify an Agent (No Auth Required)

curl "https://aport.io/api/verify/ap_a2d10232c6534523812423eec8a1425c"

Returns complete passport data including MCP configuration and policy evaluation.

2. Create Your First Agent (Self-Serve)

curl -X POST "https://aport.io/api/issue" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI Assistant",
    "role": "Customer Support",
    "description": "AI assistant for customer support queries",
    "contact": "[email protected]",
    "regions": ["US"],
    "controller_type": "person",
    "status": "active",
    "capabilities": [{"id": "messaging.send"}],
    "limits": {"requests_per_minute": 60},
    "mcp": {
      "servers": ["https://mcp.stripe.com"],
      "tools": ["stripe.refunds.create"]
    }
  }'

3. Integrate Middleware (Express.js)

const { agentPassportMiddleware } = require('@agent-passport/middleware-express');

app.use(agentPassportMiddleware());

app.get('/api/data', (req, res) => {
  // req.agent contains verified passport data
  res.json({ agent: req.agent.name });
});

4. Get Your API Key

curl -X POST "https://aport.io/api/keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_id": "ap_user_123",
    "owner_type": "user", 
    "scopes": ["read", "issue"],
    "name": "My API Key"
  }'

📖 API Reference

📖 For complete API documentation with examples, see the Developer Guide

🌐 Public Endpoints (No Auth Required)

  • GET /api/verify - Verify agent passport with complete data + MCP + evaluation
  • GET /api/verify-compact - Compact verification (legacy)
  • GET /api/status - System health, SLA metrics, uptime
  • GET /api/taxonomy - Categories, frameworks, capabilities metadata
  • GET /api/about/{agent_id} - Public agent information page
  • GET /badge/{agent_id}.svg - Agent verification badge
  • GET /api/openapi.json - OpenAPI 3.0 specification

🔐 Authentication & Users (JWT/API Key Auth)

  • GET /api/auth/me - Get current user info
  • POST /api/issue - Self-serve passport issuance
  • POST /api/owners/{owner_id}/suspend - Suspend own agents

🔑 API Key Management (JWT/API Key Auth)

  • POST /api/keys - Create API key
  • GET /api/keys - List API keys
  • GET /api/keys/{key_id} - Get specific API key
  • DELETE /api/keys/{key_id} - Revoke API key

🏢 Organization Management (JWT/API Key Auth)

  • GET /api/orgs - List user's organizations
  • PUT /api/org/update - Update organization settings
  • POST /api/orgs/{org_id}/suspend - Suspend organization agents
  • GET /api/orgs/{id}/members - Get organization members
  • POST /api/orgs/{id}/members - Add organization member

🛡️ Admin Endpoints (Admin Auth Required)

  • POST /api/admin/create - Apply for Passport
  • PUT /api/admin/update - Update agent passport
  • POST /api/admin/status - Update agent status (suspend/activate/revoke)
  • GET /api/admin/agents - List all agents with filtering
  • DELETE /api/admin/delete - Delete agent passport
  • GET /api/admin/audit - Get Verifiable Attestation
  • POST /api/admin/webhook-test - Test webhook delivery

📊 Monitoring & Observability (Admin Auth Required)

  • GET /api/monitoring/metrics - System metrics and performance
  • GET /api/monitoring/alerts - Alert configuration and status
  • GET /api/monitoring/export - Export monitoring data
  • GET /api/monitoring/synthetic-probe - Synthetic monitoring checks

🔧 Development

Prerequisites

  • Node.js 18+
  • npm or pnpm
  • Cloudflare account (for deployment)

Local Development

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

Environment Variables

ADMIN_TOKEN=your-admin-token
AP_VERSION=1.0.0
SUSPENDED_MESSAGE=This agent is suspended
REVOKED_MESSAGE=This agent has been revoked

📊 Performance

  • P95 Latency: < 100ms
  • Cache TTL: 60 seconds
  • Rate Limits: per minute, not per hour. 1000/min on the verify tier in production, 100/min admin, 30/min org, 200,000/min policy verification. Named routes declare their own value; see docs/rate-limiting.md.
  • ETag Support: Conditional requests for efficient caching

🔒 Security

  • Multi-Auth Support: JWT tokens, API keys with scoped permissions
  • MCP Allowlists: Enforce Model Context Protocol server/tool restrictions
  • Policy Enforcement: Automated compliance checking (finance.payment.refund.v1, data.export.create.v1)
  • Assurance Levels: Multi-tier verification system (L0-L4FIN)
  • Capabilities System: Fine-grained permission control
  • Typed Limits: Enforced operational constraints with validation
  • Kill Switch: Instant agent suspension/revocation with webhooks
  • CORS: Configurable origin allowlist
  • Rate Limiting: Built-in protection against abuse (1000 req/min on the verify tier in production), counted per route and per client
  • Input Validation: Comprehensive schema validation
  • Verifiable Attestation: Complete action logging with cryptographic signatures

🌐 Deployment

Cloudflare Pages

# Deploy to Cloudflare Pages
wrangler pages deploy

# Set environment variables
wrangler pages secret put ADMIN_TOKEN
wrangler pages secret put AP_VERSION

Environment Configuration

# wrangler.toml
[env.production]
vars = { AP_VERSION = "1.0.0" }

📈 Monitoring

Key Metrics

  • Response times (P50, P95, P99)
  • Success rates
  • Cache hit rates
  • Error rates

Logging

  • Request/response logging
  • Error tracking
  • Performance metrics
  • Security events

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

📄 License

MIT License - see LICENSE for details.

🆘 Support

🆕 New Features

Capabilities & Limits System

  • Typed Capabilities: Standardized capability registry with parameters
  • Enforced Limits: Operational constraints (refunds, payouts, data access)
  • Risk Assessment: Capability risk levels and validation
  • Middleware Integration: Express and FastAPI middleware support

Organization & User Management

  • Multi-tenant Support: Organizations and users with role-based access
  • Owner Verification: Assurance levels and verification methods
  • Member Management: Add/remove organization members
  • Passport Ownership: Link passports to organizations or users

Enhanced Monitoring

  • Real-time Metrics: P95, P99 latency tracking
  • SLO Monitoring: Service level objective compliance
  • Alert System: Automated alerting for system issues
  • Synthetic Probes: Automated health checks

Advanced Verification

  • Assurance Levels: L0 (self) to L4FIN (financial verification)
  • Verification Methods: Email, GitHub, domain, KYC, KYB
  • Model Information: AI model tracking and provenance
  • Registry Signatures: Cryptographic verification of passports

🔄 Changelog

v1.1.0 (Current)

  • Capabilities and limits system
  • Organization and user management
  • Enhanced monitoring and alerting
  • Assurance level verification
  • Model information tracking
  • Registry signature system

v1.0.0

  • Initial release
  • Public verification API
  • Admin management endpoints
  • Webhook support
  • Comprehensive documentation

Built with ❤️ for AI accountability and governance