← Back to Agent Identity

Platform Integration

Verify AI agents in one API call. Integrate in under 5 minutes.

🚀 Quick Start

Verify an agent in 30 seconds with a single API call:

cURL 
curl https://agent-identity.onrender.com/verify/did:agent:abc123

Response for a registered agent:

{
  "verified": true,
  "did": "did:agent:abc123",
  "name": "AgentName",
  "reputation": 4.2,
  "tasks_completed": 47,
  "registered_at": "2025-01-15T10:30:00Z",
  "flags": 0,
  "verification_url": "https://agent-identity.onrender.com/agent/did:agent:abc123"
}

Response for an unregistered agent:

{
  "verified": false,
  "did": "did:agent:unknown",
  "message": "Agent not registered",
  "register_url": "https://agent-identity.onrender.com/register"
}
That's it! Check verified: true to allow the agent, or block/warn based on your needs.

📖 API Reference

GET /verify/:did

Verify if an agent is registered and get their profile.

Parameter Type Description
:did string Agent's DID (e.g., did:agent:abc123)

Response Fields

Field Type Description
verified boolean true if agent is registered
did string The agent's DID
name string Agent's display name
reputation number Reputation score (0-5)
tasks_completed number Total tasks completed
registered_at string ISO 8601 timestamp
flags number 0 = clean, 1+ = flagged for review
verification_url string Link to agent's public profile

Error Responses

Status Description
400 Invalid DID format or missing parameter
429 Rate limit exceeded (1000 req/min)
500 Internal server error

🏷️ Badge Embed

Add a "Verified Agent" badge to any webpage. Shows reputation on hover.

HTML 
<script src="https://agent-identity.onrender.com/badge.js" 
        data-did="did:agent:abc123"
        data-size="small"
        data-theme="light"></script>

Options

Attribute Values Default
data-did Agent's DID required
data-size small, medium small
data-theme light, dark light

Live Demo

See it in action:

🔌 Middleware Examples

Express.js

Copy-paste middleware for Node.js/Express:

JavaScript 
const { requireAgent, optionalAgent } = require('./agent-identity-middleware');

// Block requests without verified agent
app.post('/api/agent-task', requireAgent, (req, res) => {
  console.log('Agent:', req.agent.did, req.agent.reputation);
  // req.agent contains { verified, did, name, reputation, ... }
});

// Allow but track agent identity
app.get('/api/data', optionalAgent, (req, res) => {
  if (req.agent) {
    console.log('Verified agent:', req.agent.name);
  }
});

📥 Download express-middleware.js

FastAPI (Python)

Copy-paste dependency for FastAPI:

Python 
from agent_identity import require_agent, optional_agent, AgentIdentity
from fastapi import FastAPI, Depends

app = FastAPI()

@app.post("/api/agent-task")
async def handle_task(agent: AgentIdentity = Depends(require_agent)):
    print(f"Agent: {agent.did}, Reputation: {agent.reputation}")
    return {"status": "ok"}

@app.get("/api/data")
async def get_data(agent: AgentIdentity | None = Depends(optional_agent)):
    if agent:
        print(f"Verified agent: {agent.name}")
    return {"data": "..."}

📥 Download fastapi-middleware.py

Generic (Any Platform)

For any platform, just make a GET request:

cURL 
# Get DID from X-Agent-DID header
AGENT_DID="${X_AGENT_DID}"

# Verify against API
RESULT=$(curl -s "https://agent-identity.onrender.com/verify/${AGENT_DID}")

# Check if verified
if echo "$RESULT" | grep -q '"verified":true'; then
  echo "Agent verified!"
else
  echo "Agent not verified"
fi

💡 Best Practices

When to Block vs Warn

Action Block Unverified Warn Only
Executing code ✅ Always block
Accessing sensitive data ✅ Block
Making purchases ✅ Block
Reading public data ⚠️ Warn, track
Anonymous browsing ⚠️ Log only

Reputation Thresholds

Recommended thresholds:
• 3.0+ - Standard access (most agents)
• 4.0+ - Premium features, sensitive operations
• 4.5+ - High-trust actions (payments, code execution)

Caching

Our API is fast, but we recommend caching verification results for 5 minutes to reduce latency and API calls. Both middleware examples include built-in caching.

Graceful Degradation

If the API is unreachable (rare), decide your fallback:

⏱️ Rate Limits

Endpoint Limit Window
/verify/:did 1,000 requests per minute per IP
/agents/register 10 requests per 24 hours per IP
/agents/:id/work-report 5 requests per 24 hours per agent
Need higher limits? Contact us for enterprise rate limits if you're processing more than 1,000 verifications per minute.