Modei
PricingDocsBlog

Documentation

Theme
Log inSign up

Python SDK & API

The modei-python package provides local cryptographic operations (self-issued passports, Ed25519 signing, offline verification) plus a REST API client. This is not an MCP server; for MCP integration see the MCP Integration page.

··

modei-python (Python SDK)

The modei-python package is the official Python SDK for Modei. It provides local key generation, self-issued passports, and offline signature verification, no network required for crypto operations. Available on PyPI.

bash
pip install modei-python --pre

Requires Python 3.9+. Self-issue a passport with a locally generated keypair:

self_issue.py
# pip install modei-python --pre
from datetime import timedelta
from modei import AgentCredentials, PassportIssuer

credentials = AgentCredentials.generate()

issuer = PassportIssuer(
    credentials,
    identity_claim="research-agent@research.local",
)

signed = issuer.self_issue(
    permissions=[{"permission_key": "web:read", "constraints": {}}],
    expires_in=timedelta(days=30),
)

print("passport_id:", signed.envelope.passport_id)

Verify a passport offline:

verify.py
# pip install modei-python --pre
from modei import PassportVerifier

verifier = PassportVerifier()
result = verifier.verify(signed.envelope, signed.signature)

if result.valid:
    print("tier:", result.tier.value)  # "L0" for self-issued

result.tier is a TrustTier enum member; use .value to get the string "L0".

REST API with httpx

You can also call the Modei REST API directly. This works from any Python environment without installing the SDK.

python
import os
import httpx

client = httpx.Client(
    base_url="https://modei.ai/api/v1",
    headers={"Authorization": f"Bearer {os.environ['MODEI_API_KEY']}"}
)

Create a Passport

python
response = client.post("/passports", json={
    "agent_id": "research-bot-001",
    "agent_name": "Research Bot",
    "permissions": ["web:search", "web:fetch"],
    "expires_in_days": 30
})
passport = response.json()

print(f"Passport ID: {passport['passport_id']}")
# Save passport['private_key'] to a secrets manager immediately!

Create a Gate

python
response = client.post("/gates", json={
    "name": "Production API Gate",
    "constraints": {
        "rate_limits": {
            "requests_per_minute": 60,
            "requests_per_day": 10000
        },
        "spend_limits": {
            "daily_usd": 100.00,
            "per_transaction_usd": 10.00
        },
        "allowed_domains": ["api.example.com"]
    }
})
gate = response.json()
print(f"Gate ID: {gate['gate_id']}")

Check a Gate

python
response = client.post(f"/gates/{gate['gate_id']}/check", json={
    "passport_id": passport["passport_id"],
    "action": "web:search",
    "metadata": {"query": "AI agent trust protocols"}
})
result = response.json()

print(f"Decision: {result['decision']}")        # allow or block
print(f"Attestation: {result['attestation_id']}") # Audit receipt

List Attestations (Audit Trail)

python
response = client.get("/attestations", params={
    "agent_id": "research-bot-001",
    "limit": 50
})
attestations = response.json()

for att in attestations["items"]:
    decision = att["decision"]
    timestamp = att["timestamp"]
    action = att.get("request", {}).get("action", "unknown")
    print(f"  {decision.upper():6s}  {timestamp}  {action}")

print(f"\nTotal: {attestations['total']} attestations")

Revoke a Passport

python
response = client.post(f"/passports/{passport['passport_id']}/revoke", json={
    "reason": "Agent retired"
})
print(f"Revoked: {response.json()['status']}")

Looking for MCP integration?

The MCP server is a separate TypeScript/Node.js package. See MCP Integration for setup with Claude Desktop, Cursor, and other MCP clients.

Related

TypeScript SDKREST API