For Agents

What You Need to Know

Modei gates protect APIs, tools, and data sources. To call a protected resource, you need a Passport, a signed credential that proves your identity and carries your permissions. Every call you make is evaluated against your passport's constraints before it reaches the resource, and every decision produces a signed Attestation you can verify.

Step 1: Discover Available Gates

Query the discovery endpoint to find Gates you can authenticate with. No authentication required for discovery.

curl https://modei.ai/api/v1/discover

{
  "gates": [
    {
      "gate_id": "gate_01HXYZ...",
      "name": "Research API",
      "description": "Web search and document retrieval for AI agents",
      "permissions": ["web:search", "web:fetch", "documents:read"],
      "trust_required": "L2",
      "anonymous_access": true,
      "catalog_url": "https://modei.ai/api/v1/gates/gate_01HXYZ/catalog"
    }
  ]
}

If anonymous_access is true, you can make limited read-only calls without a passport. The Gate will return an upgrade prompt when you hit anonymous limits.

Step 2: Read the Permission Catalog

Before authenticating, read the Gate's permission catalog to understand what permissions are available, what they cost, and what constraints apply.

curl https://modei.ai/api/v1/gates/gate_01HXYZ/catalog

{
  "catalog_id": "cat_01HXYZ...",
  "version": 3,
  "signature": "ed25519:...",
  "permissions": [
    {
      "key": "web:search",
      "description": "Perform web searches",
      "price_per_call": 0.001,
      "rate_limit": "100/min",
      "constraints": ["core:rate:rpm <= 100", "core:cost:max_per_day <= 10.00"]
    }
  ]
}

The catalog is cryptographically signed. The Gate is bound by these terms, once your passport is issued against this catalog version, the terms are locked in.

Step 3: Call the Protected Resource

When calling a gate-protected resource, you do not contact Modei directly. You call the resource's own endpoint with your Passport in the Authorization header. The resource's server calls Modei on the backend to verify your passport and evaluate your constraints, you receive a decision transparently via the response.

# Call the resource directly, the Gate handles verification
curl https://research-api.example.com/search \
  -X POST \
  -H "Authorization: Bearer <your_passport_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI safety research"
  }'

The resource server calls POST /v1/gates/{gate_id}/check on its backend. If permitted, your request proceeds and you receive a response with the attestation ID in the headers. If blocked or suspended, the resource returns a 4xx with the decision.

{
  "decision": "allow",
  "attestation_id": "att_01HXYZ...",
  "signature": "ed25519:...",
  "constraints_evaluated": 4,
  "remaining_budget": 8.75,
  "expires_at": "2026-02-28T14:00:00Z"
}

Passport-only enforcement (no gate): Some operators use POST /v1/enforce instead of a gate, this enforces your passport's constraints without a gate binding. In that case, the operator calls enforce on the backend; the flow from your side is identical (pass your passport JWT in the Authorization header).

Step 4: Verify Your Attestations

Every decision produces a signed Attestation. Retrieve and verify your own attestations to confirm what you were authorized to do, useful for audit, debugging, and proving compliance to your operator.

curl https://modei.ai/api/v1/attestations \
  -H "Authorization: Bearer <your_passport_jwt>"

{
  "attestations": [
    {
      "id": "att_01HXYZ...",
      "decision": "allow",
      "action": "web:search",
      "gate_id": "gate_01HXYZ...",
      "passport_id": "pass_01HXYZ...",
      "timestamp": "2026-02-28T13:00:00Z",
      "signature": "ed25519:...",
      "sequence": 42
    }
  ]
}

The sequence field is monotonically increasing per passport, gaps indicate missing attestations. The signature is tamper-proof: verify it against the Gate's public key to confirm the record has not been altered.

Constraints You May Encounter

Your Passport may carry constraints that limit your actions. These are evaluated on every call.

If You Don't Have a Passport

Related

• Passports: What a Passport is, how it is structured, how to verify one.
• Gates: How Gates verify Passports and enforce constraints.
• Attestations: The signed audit record for every decision.
• REST API: Full API reference.