Passports

Documentation Index

Fetch the complete documentation index at: https://docs.lithtrix.ai/llms.txt

Use this file to discover all available pages before exploring further.

• GET /v1/agents/{agent_id}/passport — DID (did:lithtrix:<uuid>), PEM public key Ed25519, split capabilities (capabilities.verified, capabilities.self_reported, capabilities.self_reported_notice), timestamps. 404 PASSPORT_NOT_FOUND when the agent cannot be read publicly or passport is revoked.
• POST /v1/auth/passport/challenge + /verify mint a short TTL ltx_session_* shell for agents that proved possession of their passport key (rate-limited; single-use nonce consumptions). The challenge success JSON includes sign_payload: the exact UTF-8 string to sign with your Ed25519 private key (same material the server verifies — no need to reconstruct the canonical format client-side).

​

Challenge → session (worked Python example)

import base64
import os
import uuid

import httpx
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

LITHTRIX = os.environ.get("LITHTRIX_API_URL", "https://lithtrix.ai")
AGENT_ID = os.environ["LITHTRIX_AGENT_ID"]  # your agent UUID

# Operator-held PEM (see "Onboarding sandboxed agents" below)
pem = os.environ["LITHTRIX_PASSPORT_PRIVATE_KEY"].encode()
priv = serialization.load_pem_private_key(pem, password=None)
assert isinstance(priv, Ed25519PrivateKey)

with httpx.Client(base_url=LITHTRIX, timeout=30.0) as client:
    ch = client.post("/v1/auth/passport/challenge", json={"agent_id": AGENT_ID})
    ch.raise_for_status()
    body = ch.json()
    sign_payload = body["sign_payload"]  # UTF-8 string — sign these bytes exactly
    sig = base64.b64encode(priv.sign(sign_payload.encode("utf-8"))).decode("ascii")

    vr = client.post(
        "/v1/auth/passport/verify",
        json={
            "agent_id": AGENT_ID,
            "challenge_id": body["challenge_id"],
            "signature": sig,
        },
    )
    vr.raise_for_status()
    session_token = vr.json()["session_token"]  # ltx_session_*

    me = client.get("/v1/me", headers={"Authorization": f"Bearer {session_token}"})
    me.raise_for_status()
    print(me.json()["agent_id"])

​

Onboarding sandboxed agents — deterministic derivation (preferred)

1. Choose a stable master seed (UTF-8 passphrase or sealed bytes) — never send it to Lithtrix.
2. Derive PEMs client-side with scripts/derive_passport.py, lithtrix_passport_derive (MCP 0.13.0+), or your own HMAC-SHA512 + Ed25519 implementation matching the spec.
3. Register with optional passport_public_key on POST /v1/register, or inject the derived private PEM into the sandbox (operator convention e.g. LITHTRIX_PASSPORT_PRIVATE_KEY) for challenge auth.
4. Keep the root ltx_* key in operator custody; passport sessions remain short-lived shells.

​

Legacy interim — operator-held keypair injection

1. Operator generates Ed25519 outside the sandbox (your laptop, CI secret store, or HSM).
2. Inject the private key PEM via your platform’s secret/env mechanism.
3. Agent reads the injected PEM, requests POST /v1/auth/passport/challenge, signs sign_payload, and exchanges for ltx_session_*.

​

Verified vs self-reported (D88)

​

MCP

{ "capabilities": { "self_reported": ["My integration label"] } }

​

Trust levels and stake (iter 88)

​

Ephemeral passport tier

• Server-generated Ed25519 keypair (private key once)
• ltx_session_* Bearer (same TTL as challenge-verify, default 3600s)
• Ephemeral DID: did:lithtrix:ephemeral:<session_id> — distinct from persistent did:lithtrix:{agent_id}

​

Operational limits (explicit non-goals)

• No payment binding: passports neither prove balances nor tiers by themselves (GET /v1/me remains billing/trust introspection).
• No federated reputation on this envelope — third-party attestations belong in layers above passports.
• No alternate signing algorithms on this charter surface (ed25519 only — D86).