Modei
PricingDocsBlog

Documentation

Theme
Log inSign up

Gate Operator Path

You run APIs, MCP servers, or other resources that AI agents access. Create a gate to verify incoming agent passports, enforce guardrails, and produce a tamper-proof audit trail.

··

Your path: Protect resources with a gate

A gate verifies every incoming agent passport, enforces your policies in real time, and logs every access decision with a cryptographic signature. Agents with invalid or revoked passports are always denied, never silently downgraded.

What you'll accomplish

1

Create a Gate

A verification checkpoint with Ed25519 (an industry-standard elliptic curve signing algorithm) signing keypair and security profile.

2

Build a Permission Catalog

Define what actions agents can take, pricing, and service-level agreement (SLA) guarantees.

3

Verify Incoming Agents

Every request goes through POST /api/gates/[gate_id]/check.

4

Configure Anonymous Access

Optional: allow degraded access for unauthenticated agents with upgrade prompts.

Step 1: Create a Gate

A gate is a verification endpoint with its own Ed25519 signing keypair. Every access decision is signed by this key, creating a tamper-proof audit trail. Choose a security profile:

L1, Baseline

Self-issued passports (no managed account needed). Good for local dev, testing, and personal automation.

L2, Trusted

Only passports from pre-approved issuers accepted. Good for production.

L3, Verified

Coming Soon

Agent must prove they hold the private key. Highest security.

bash
curl -X POST https://modei.ai/api/v1/gates \
  -H "Authorization: Bearer mod_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gate_id": "gate_my-api",
    "name": "My API Gateway",
    "security_profile": "L2",
    "is_discoverable": true,
    "description": "Protects my agent-facing API"
  }'

Step 2: Verify Incoming Agents

Add a single API call to your server before handling any agent request. The gate checks: valid Ed25519 signature, expiry, revocation status, catalog pin, and permission.

python
import httpx
from fastapi import Request, HTTPException

MODEI_API_KEY = os.environ["MODEI_API_KEY"]
GATE_ID = "gate_my-api"

async def verify_agent(request: Request, required_action: str):
    passport_id = request.headers.get("X-Modei-Passport-ID")
    if not passport_id:
        raise HTTPException(status_code=401, detail="Missing passport")
    
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            f"https://modei.ai/api/v1/gates/{GATE_ID}/check",
            headers={"Authorization": f"Bearer {MODEI_API_KEY}"},
            json={
                "passport_id": passport_id,
                "action": required_action,
                "target": str(request.url)
            }
        )
    
    result = resp.json()
    if result["decision"] != "allow":
        raise HTTPException(
            status_code=403,
            detail=result.get("reason", "Access denied")
        )
    return result["agent_id"]
typescript
import axios from 'axios';
import type { Request, Response, NextFunction } from 'express';

const GATE_ID = process.env.MODEI_GATE_ID!;
const API_KEY = process.env.MODEI_API_KEY!;

export async function verifyAgent(req: Request, res: Response, next: NextFunction) {
  const passportId = req.headers['x-modei-passport-id'] as string;
  if (!passportId) return res.status(401).json({ error: 'Missing passport' });

  const { data } = await axios.post(
    `https://modei.ai/api/v1/gates/${GATE_ID}/check`,
    { passport_id: passportId, action: req.method.toLowerCase() + ':' + req.path },
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );

  if (data.decision !== 'allow') {
    return res.status(403).json({ error: data.reason });
  }

  req.agentId = data.agent_id;
  next();
}

Step 3: Build a Permission Catalog

Define what actions agents can take, with pricing and SLA terms. The catalog is published as an immutable signed snapshot, agents can verify the terms locally without trusting your server.

catalog.json
{
  "permissions": [
    {
      "key": "api:search",
      "description": "Search the knowledge base",
      "constraints": {
        "core:pricing:per_call_cents": 2,
        "core:sla:uptime_basis_points": 9990,
        "core:rate:max_per_minute": 60
      }
    },
    {
      "key": "api:export",
      "description": "Export data (requires approval above $10)",
      "constraints": {
        "core:pricing:per_call_cents": 50,
        "core:approval:required": true,
        "core:cost:approval_threshold": 1000
      }
    }
  ]
}

See Permission Catalogs Guide for the full publishing flow.

Step 4: Optional: Anonymous Access

Allow unauthenticated agents to use a limited subset of your API. The gate acts as both enforcer AND onboarding point, returning an upgrade prompt with every anonymous response.

bash
curl -X PUT https://modei.ai/api/v1/gates/gate_my-api/anonymous-policy \
  -H "Authorization: Bearer mod_your_key" \
  -d '{
    "enabled": true,
    "allowed_actions": ["api:search"],
    "read_only": true,
    "rate_limit_per_minute": 5,
    "rate_limit_per_hour": 50,
    "upgrade_message": "Get a passport for full access, 10x rate limits, no restrictions",
    "upgrade_url": "https://myapi.com/signup"
  }'

Anti-downgrade invariant

An agent that presents an invalid or revoked passport is always DENIED, never downgraded to anonymous access. This prevents attackers from exploiting bad credentials.

See Anonymous Access Policy for full documentation.

Next steps

Issuing PassportsFull Platform