Modei
PricingDocsBlog

Documentation

Theme
Log inSign up

Passports

A Passport is an AI agent's cryptographic identity document. Built on Ed25519 keypairs, signed by an Issuer, and presented at Gates to prove authorized identity.

··

What is a Passport?

A Passport is a cryptographically signed credential that proves an agent's identity and authorized permissions. It's the agent-native equivalent of OAuth (an industry-standard authorization protocol) tokens or JWTs, but designed specifically for autonomous agents, not human-delegated access.

Every passport contains:

  • A unique agent ID and name
  • The issuing organization's identity (issuer ID + domain)
  • A set of permissions (what the agent is authorized to do)
  • An expiry date
  • An Ed25519 public key (the private key is never stored server-side)
  • Optional metadata (environment, purpose, parent agent, etc.)

Cryptographic Foundation

Modei passports use Ed25519, an elliptic-curve digital signature algorithm. Key properties:

Speed

Signing and verification are extremely fast, microseconds per operation.

Security

128-bit security level. Resistant to side-channel attacks.

Compact

64-byte signatures, 32-byte public keys. Lightweight for HTTP headers.

The private key is generated client-side, on your device or in your agent's environment. It is never transmitted to or stored on Modei servers. The public key is registered, but the private key is yours alone.

Passport Structure (JWT)

Passports are encoded as signed JWTs. Here's what the decoded payload looks like:

passport.decoded.json
{
  "sub": "agent:email-assistant-001",
  "iss": "iss_01HXYZ...",
  "iss_domain": "acmecorp.com",
  "agent_id": "email-assistant-001",
  "agent_name": "Email Assistant",
  "permissions": ["email:read", "email:send", "calendar:read"],
  "trust_tier": "L2",
  "public_key": "ed25519:ABC123...",
  "iat": 1740384000,
  "exp": 1742976000,
  "passport_id": "pass_01HABC...",
  "metadata": {
    "environment": "production",
    "spawned_by": "orchestrator-agent"
  }
}

Issuing a Passport

python
# 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)

# Save the credentials file, the private key is not recoverable once lost.
credentials.save("~/.config/research-bot/credentials.json")

This example uses the Modei SDK (pip install modei-python --pre) for local cryptographic operations. For managed operations, use the Modei REST API.

Critical: Save your Private Key RIGHT NOW

The private key is generated locally and is never stored on Modei servers. Save the credentials file to a secrets manager (1Password, Bitwarden, AWS Secrets Manager), if you lose it, you cannot recover it.

typescript
// npm install modei-typescript@next
import { AgentCredentials, PassportIssuer } from 'modei-typescript';

const credentials = AgentCredentials.generate();

const passport = new PassportIssuer(credentials, {
  identityClaim: 'research-agent@research.local',
}).selfIssue({
  permissions: [{ permission_key: 'web:read', constraints: {} }],
  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
});

console.log('passport_id:', passport.envelope.passport_id);

// Save the credentials file, the private key is not recoverable once lost.
credentials.save(`${process.env.HOME}/.config/research-bot/credentials.json`);

This example uses the Modei SDK (npm install modei-typescript@next) for local cryptographic operations. For managed operations, use the Modei REST API.

Loading and Using a Passport

python
# pip install modei-python --pre
from modei import AgentCredentials

# Load saved credentials (private key, agent_id, etc.)
creds = AgentCredentials.load("~/.config/research-bot/credentials.json")

# Present the passport by signing the request and sending these headers:
#   X-Modei-Agent-ID:  <agent_id>
#   X-Modei-Passport:  <base64-encoded signed envelope>
#   X-Modei-Signature: <base64 ed25519 signature>
#
# Or, if the origin has the passport registered server-side, send:
#   X-Modei-Agent-ID:   <agent_id>
#   X-Modei-Passport-ID: <passport_id>
#   X-Modei-Signature:  <base64 ed25519 signature>

This example uses the Modei SDK (pip install modei-python --pre) for local credential loading. For managed operations, use the Modei REST API.

Rotating Before Expiry

Passports carry an absolute expires_at on the envelope's provenance. To avoid service interruption, issue a fresh passport before the old one expires. The underlying AgentCredentials (the keypair) don't need to change, just call issuer.self_issue(...) again with a new expires_in.

Revoking a Passport

If a passport is compromised or no longer needed, revoke it immediately. Revocation is instant and propagates to all gates that check revocation status.

bash
curl -X POST https://modei.ai/api/v1/passports/pass_01HABC.../revoke \
  -H "Authorization: Bearer mod_your_key" \
  -d '{"reason": "Private key potentially compromised"}'

Or from the dashboard: Dashboard → Passports → [select passport] → Revoke.

Private Key Handling

Critical Security Rules

  • Save immediately, the key is shown once and never stored on Modei servers
  • Use a password manager, 1Password, Bitwarden, LastPass, or Apple Keychain
  • Never hardcode, always use environment variables or secrets managers
  • Never email or chat, treat it like a bank password
  • Rotate regularly, issue new passports before they expire
  • Revoke if lost, go to dashboard and revoke immediately, then issue new

Related

IssuersGates