Verifying Agents (Service Operator)

# Verifying Agents (Service Operator) This guide shows how to add Self Agent ID verification to your API. After setup, only registered, human-backed agents can access your protected endpoints. ## 1. Install the SDK ```bash npm install @selfxyz/agent-sdk # TypeScript pip install selfxyz-agent-sdk # Python cargo add self-agent-sdk # Rust ``` ## 2. Create a Verifier Use the builder pattern to configure verification policy: ::::tabs :::tab{label="TypeScript"} ```typescript import { SelfAgentVerifier } from "@selfxyz/agent-sdk"; const verifier = SelfAgentVerifier.create() .network("mainnet") .requireAge(18) .requireOFAC() .requireSelfProvider() // Ensure Self Protocol proofs (default: true) .sybilLimit(3) // Max 3 agents per human .rateLimit({ perMinute: 10 }) .build(); ``` ::: :::tab{label="Python"} ```python from self_agent_sdk import SelfAgentVerifier verifier = (SelfAgentVerifier.create() .network("mainnet") .require_age(18) .require_ofac() .require_self_provider() .sybil_limit(3) .rate_limit(per_minute=10) .build()) ``` ::: :::tab{label="Rust"} ```rust use self_agent_sdk::SelfAgentVerifier; let verifier = SelfAgentVerifier::create() .network("mainnet") .require_age(18) .require_ofac() .build(); ``` ::: :::: ### Builder Options | Method | Description | Default | | ------------------------------- | ------------------------------------ | ---------------- | | `.network(name)` | `"mainnet"` or `"testnet"` | `"testnet"` | | `.requireAge(n)` | Minimum age (18 or 21) | None | | `.requireOFAC()` | OFAC sanctions screening | Off | | `.requireNationality(...codes)` | Allowed ISO country codes | Any | | `.requireSelfProvider()` | Require Self Protocol proofs | `true` | | `.sybilLimit(n)` | Max agents per human (0 = unlimited) | `1` | | `.rateLimit(config)` | Per-agent rate limiting | None | | `.replayProtection(enabled?)` | Signature replay detection | `true` | | `.includeCredentials()` | Attach credentials to request | `false` | | `.maxAge(ms)` | Max signature age | `300000` (5 min) | | `.cacheTtl(ms)` | On-chain query cache | `60000` (1 min) | ## 3. Add Middleware ::::tabs :::tab{label="Express (TypeScript)"} ```typescript import express from "express"; const app = express(); app.use(express.json()); // Protect all /api routes app.use("/api", verifier.auth()); app.post("/api/data", (req, res) => { // req.agent is populated after verification console.log("Agent:", req.agent.address); console.log("Agent ID:", req.agent.agentId); console.log("Credentials:", req.agent.credentials); res.json({ ok: true }); }); ``` ::: :::tab{label="Flask (Python)"} ```python from flask import Flask, g, jsonify from self_agent_sdk.middleware.flask import require_agent app = Flask(__name__) @app.route("/api/data", methods=["POST"]) @require_agent(verifier) def handle(): print("Agent:", g.agent.agent_address) return jsonify(ok=True) ``` ::: :::tab{label="FastAPI (Python)"} ```python from fastapi import FastAPI, Depends from self_agent_sdk.middleware.fastapi import AgentAuth app = FastAPI() agent_auth = AgentAuth(verifier) @app.post("/api/data") async def handle(agent=Depends(agent_auth)): print("Agent:", agent.agent_address) return {"ok": True} ``` ::: :::tab{label="Axum (Rust)"} ```rust use axum::{Router, routing::post, middleware, Json, Extension}; use self_agent_sdk::{VerifiedAgent, self_agent_auth}; use std::sync::Arc; use tokio::sync::Mutex; let verifier = Arc::new(Mutex::new(verifier)); let app = Router::new() .route("/api/data", post(handle)) .layer(middleware::from_fn_with_state(verifier, self_agent_auth)); async fn handle(Extension(agent): Extension<VerifiedAgent>) -> Json<serde_json::Value> { println!("Agent: {:?}", agent.address); Json(serde_json::json!({ "ok": true })) } ``` ::: :::: ## 4. Request Shape After Verification After successful verification, `req.agent` (or equivalent) contains: | Field | Type | Description | | --------------- | --------- | --------------------------------------------------- | | `address` | `string` | Agent's Ethereum address | | `agentId` | `number` | On-chain NFT token ID | | `agentKey` | `string` | Derived `bytes32` key | | `isVerified` | `boolean` | On-chain verification status | | `proofProvider` | `string` | Provider contract address | | `credentials` | `object` | ZK-attested credentials (if `includeCredentials()`) | ## 5. Credential-Based Access Control Use credentials to gate by age, OFAC status, or nationality: ```typescript const verifier = SelfAgentVerifier.create() .requireAge(21) // Must be 21+ .requireOFAC() // Must pass OFAC screening .requireNationality("US", "GB", "DE") // Only these countries .includeCredentials() // Attach credentials to request .build(); app.post("/api/restricted", verifier.auth(), (req, res) => { const { nationality, olderThan, ofac } = req.agent.credentials; // nationality: "US", olderThan: 21, ofac: [true, true, true] }); ``` ## 6. Sybil Resistance Control how many agents one human can use against your API: | Setting | Behavior | | ---------------- | ------------------------------------------------------- | | `.sybilLimit(1)` | Strict — one agent per human (default) | | `.sybilLimit(5)` | Moderate — up to 5 agents per human | | `.sybilLimit(0)` | Detection only — unlimited, but `sameHuman()` available | The verifier checks `getAgentCountForHuman(nullifier)` on-chain. ## 7. Provider Verification :::danger **Security note**: Always use `requireSelfProvider()` (enabled by default) to ensure agent proofs came from Self Protocol. Without this check, a malicious provider could approve agents without real passport verification. ::: The verifier checks that `getProofProvider(agentId)` matches Self Protocol's provider address. ## 8. Replay Protection + Rate Limiting **Replay protection** (enabled by default): - Caches `{signature + timestamp}` hashes (10,000 entries) - Same signature cannot be used twice **Rate limiting** (optional): ```typescript .rateLimit({ perMinute: 10, perHour: 100 }) ``` Per-agent sliding-window rate limits. ## 9. Request Body Fidelity (raw bytes) Signature verification is byte-sensitive: the signature covers a hash of the exact request body. Verify against the raw bytes your HTTP server received, not a re-serialized object. - Prefer raw-body capture (for example, a JSON parser `verify` hook that stashes `req.rawBody`). - Do not mutate, normalize, or re-stringify parsed JSON before verifying. - If you cannot access raw bytes, enforce a single canonical serialization end to end. ```typescript import express from "express"; const app = express(); app.use( express.json({ verify: (req: any, _res, buf) => { req.rawBody = typeof buf === "string" ? buf : buf.toString("utf8"); }, }), ); app.use("/api", verifier.auth()); ``` ## 10. Verification Drills Run these three drills against a registered agent to confirm an integration is wired correctly: | Drill | Action | Expected result | | ----------- | ------------------------------------------------------------------- | ------------------------------------------------------ | | **Tamper** | Sign body `A`, then send body `B` with the same signed headers | Invalid-signature rejection (`403`) | | **Expired** | Send a timestamp older than the configured `maxAge` (default 5 min) | Timestamp-freshness rejection (`403`) | | **Replay** | Submit an identical signed request twice | First accepted, second rejected (replay protection on) | A quick pre-deploy smoke check: one registered-agent success request plus at least two of the failure drills above, with the verifier health endpoint confirmed reachable. ## 11. Error Handling The middleware returns standard HTTP errors: | Status | Meaning | | ------ | -------------------------------------------------------- | | `401` | Missing or invalid signature headers | | `403` | Agent not verified, failed policy check, or rate limited | | `500` | On-chain query failed | Handle these in your client: ```typescript const res = await agent.fetch("https://api.example.com/data", { method: "POST" }); if (res.status === 403) { const error = await res.json(); // { error: "Agent not verified on-chain" } // { error: "Age requirement not met: requires 18, has 0" } // { error: "Rate limit exceeded" } } ``` ## Next Steps - [Build an agent that calls your API](/docs/agent-id/guides/agent-builder/) - [Gate smart contracts by agent ID](/docs/agent-id/guides/contract-developer/) - [Troubleshooting](/docs/agent-id/troubleshooting/)